fundamental-styles

CSS component library for SAP Design System. Framework-agnostic, works with any web technology.

For AI Agents

Component documentation is auto-generated from Storybook stories and available in structured markdown:

📚 Complete Component Index: docs/components/README.md - All 140+ components
📖 Per-Component Docs: docs/components/{component-name}.md - Detailed examples with modifiers
🔧 Integration Guide: docs/AI_USAGE.md - How to use these docs in AI tools
📋 Schemas: docs/schemas/*.json - Component structure definitions
♿ Accessibility: docs/accessibility.json - ARIA patterns for all components

When generating HTML/CSS, always reference the component-specific markdown file for:

Complete list of modifiers (fd-{component}--{modifier})
State classes (is-error, is-disabled, etc.)
Correct HTML structure and nesting
Accessibility requirements (ARIA attributes)

Example workflow:

User asks for a button → Read docs/components/button.md
Find the right modifier (e.g., fd-button--emphasized for primary action)
Generate HTML with proper structure and ARIA attributes

Using the MCP Server: If you have the fundamental-styles MCP server available, use these tools:

get_component_markdown - Get complete markdown documentation with all HTML examples
get_component_html - Get specific HTML variants
list_components - Browse all available components
search_components - Find components by keyword

Using Skills: Type /component-docs to browse component documentation interactively.

Quick Lookup - "I need a..."

Need	Component	Class
Button	button	`fd-button`
Text input	input	`fd-input`
Dropdown/Select	select	`fd-select`
Checkbox	checkbox	`fd-checkbox`
Radio button	radio	`fd-radio`
Toggle switch	switch	`fd-switch`
Link	link	`fd-link`
Modal/Popup	dialog	`fd-dialog`
Tooltip	popover	`fd-popover`
Dropdown menu	menu	`fd-menu`
Data table	table	`fd-table`
List of items	list	`fd-list`
Card/Tile	card	`fd-card`
Tabs	tabs	`fd-tabs`
Alert/Banner	alert, message-strip	`fd-alert`, `fd-message-strip`
Loading spinner	busy-indicator	`fd-busy-indicator`
Form field	form-item	`fd-form-item`
Icon	icon	`sap-icon--{name}`

Packages

Package	Purpose	Install
`fundamental-styles`	120 UI components	`npm i fundamental-styles`
`@fundamental-styles/common-css`	Utility classes (margins, flex)	`npm i @fundamental-styles/common-css`

Quick Start

<!-- 1. Theme (required) -->
<link href="node_modules/fundamental-styles/dist/theming/sap_horizon.css" rel="stylesheet">

<!-- 2. Components (pick what you need) -->
<link href="node_modules/fundamental-styles/dist/button.css" rel="stylesheet">
<link href="node_modules/fundamental-styles/dist/input.css" rel="stylesheet">

Component Classes (fd-*)

BEM Pattern: fd-{component}, fd-{component}--{modifier}, fd-{component}__{element}

Buttons

<button class="fd-button">Default</button>
<button class="fd-button fd-button--emphasized">Primary Action</button>
<button class="fd-button fd-button--positive">Approve</button>
<button class="fd-button fd-button--negative">Reject</button>
<button class="fd-button fd-button--transparent">Ghost/Tertiary</button>
<button class="fd-button fd-button--compact">Compact Size</button>

<!-- Button with icon -->
<button class="fd-button">
  <span class="sap-icon--add"></span> Add Item
</button>

<!-- Icon-only button -->
<button class="fd-button" aria-label="Settings">
  <span class="sap-icon--settings"></span>
</button>

<!-- Disabled state -->
<button class="fd-button" disabled aria-disabled="true">Disabled</button>

Form Inputs

<!-- Text input -->
<input class="fd-input" type="text" placeholder="Enter text">
<input class="fd-input fd-input--compact" type="text">

<!-- States -->
<input class="fd-input is-error" type="text">     <!-- Invalid -->
<input class="fd-input is-success" type="text">   <!-- Valid -->
<input class="fd-input is-warning" type="text">   <!-- Warning -->
<input class="fd-input" disabled>                 <!-- Disabled -->
<input class="fd-input" readonly>                 <!-- Read-only -->

<!-- Complete form field -->
<div class="fd-form-item">
  <label class="fd-form-label fd-form-label--required" for="name">Name</label>
  <input class="fd-input" id="name" type="text">
</div>

<!-- With error message -->
<div class="fd-form-item">
  <label class="fd-form-label" for="email">Email</label>
  <input class="fd-input is-error" id="email" type="email" aria-describedby="email-error">
  <span class="fd-form-message fd-form-message--error" id="email-error">Invalid email</span>
</div>

Select/Dropdown

<div class="fd-select">
  <div class="fd-select__control" role="combobox" aria-expanded="false" aria-haspopup="listbox" tabindex="0">
    <span class="fd-select__text-content">Select an option</span>
    <span class="fd-button fd-button--transparent fd-select__button">
      <i class="sap-icon--slim-arrow-down" role="presentation"></i>
    </span>
  </div>
</div>

Checkbox & Radio

<!-- Checkbox -->
<input type="checkbox" class="fd-checkbox" id="cb1">
<label class="fd-checkbox__label" for="cb1">
  <span class="fd-checkbox__checkmark" aria-hidden="true"></span>
  <span class="fd-checkbox__label-container">
    <span class="fd-checkbox__text">Option</span>
  </span>
</label>

<!-- Radio -->
<input type="radio" class="fd-radio" id="r1" name="group">
<label class="fd-radio__label" for="r1">
  <span class="fd-radio__text">Option</span>
</label>

Table

<table class="fd-table">
  <thead class="fd-table__header">
    <tr class="fd-table__row">
      <th class="fd-table__cell">Name</th>
      <th class="fd-table__cell">Status</th>
    </tr>
  </thead>
  <tbody class="fd-table__body">
    <tr class="fd-table__row">
      <td class="fd-table__cell">Item 1</td>
      <td class="fd-table__cell">Active</td>
    </tr>
    <tr class="fd-table__row is-selected">  <!-- Selected row -->
      <td class="fd-table__cell">Item 2</td>
      <td class="fd-table__cell">Pending</td>
    </tr>
  </tbody>
</table>

Dialog/Modal

<div class="fd-dialog fd-dialog--active">
  <div class="fd-dialog__content">
    <header class="fd-dialog__header fd-bar fd-bar--header">
      <div class="fd-bar__left">
        <div class="fd-bar__element">
          <h3 class="fd-title fd-title--h5">Dialog Title</h3>
        </div>
      </div>
      <div class="fd-bar__right">
        <div class="fd-bar__element">
          <button class="fd-button fd-button--transparent" aria-label="Close">
            <span class="sap-icon--decline"></span>
          </button>
        </div>
      </div>
    </header>
    <div class="fd-dialog__body">Content here</div>
    <footer class="fd-dialog__footer fd-bar fd-bar--footer">
      <div class="fd-bar__right">
        <button class="fd-button fd-button--emphasized">Save</button>
        <button class="fd-button fd-button--transparent">Cancel</button>
      </div>
    </footer>
  </div>
</div>

Alert/Message Strip

<!-- Inline message -->
<div class="fd-message-strip fd-message-strip--error" role="alert">
  <p class="fd-message-strip__text">Error message here</p>
</div>
<div class="fd-message-strip fd-message-strip--success" role="alert">
  <p class="fd-message-strip__text">Success message</p>
</div>
<div class="fd-message-strip fd-message-strip--warning" role="alert">
  <p class="fd-message-strip__text">Warning message</p>
</div>
<div class="fd-message-strip fd-message-strip--information" role="alert">
  <p class="fd-message-strip__text">Info message</p>
</div>

Icons

<!-- Icon syntax: sap-icon--{icon-name} -->
<span class="sap-icon--home"></span>
<span class="sap-icon--settings"></span>
<span class="sap-icon--add"></span>
<span class="sap-icon--delete"></span>
<span class="sap-icon--edit"></span>
<span class="sap-icon--search"></span>
<span class="sap-icon--filter"></span>
<span class="sap-icon--save"></span>
<span class="sap-icon--cancel"></span>
<span class="sap-icon--accept"></span>
<span class="sap-icon--decline"></span>
<span class="sap-icon--slim-arrow-down"></span>
<span class="sap-icon--slim-arrow-right"></span>

<!-- Full icon list: https://sap.github.io/fundamental-styles/?path=/docs/components-icons-sap-icons -->

State Classes

Apply these to components for different states:

Class	Usage
`is-disabled`	Disabled (use with `disabled` attr)
`is-selected`	Selected item
`is-active`	Active/pressed state
`is-focus`	Focused state
`is-error`	Error/invalid state
`is-success`	Success/valid state
`is-warning`	Warning state
`is-information`	Information state

Utility Classes (sap-*)

From @fundamental-styles/common-css:

Spacing

/* Margins - all sides */
sap-margin-tiny|small|medium|large

/* Margins - specific side */
sap-margin-top-tiny      sap-margin-bottom-small
sap-margin-begin-medium  sap-margin-end-large
sap-margin-x-small       sap-margin-y-medium

/* Padding - same pattern */
sap-padding-tiny|small|medium|large
sap-padding-top-*|bottom-*|begin-*|end-*

Flexbox

sap-flex                     /* display: flex */
sap-flex--column             /* flex-direction: column */
sap-flex--row                /* flex-direction: row */
sap-flex--center             /* justify + align center */
sap-flex--justify-center     /* justify-content: center */
sap-flex--align-items-center /* align-items: center */
sap-flex--wrap               /* flex-wrap: wrap */
sap-flex--gap-tiny|small|medium|large

Display

sap-display-none             /* Hide element */
sap-display-block
sap-display-inline-block

Design Tokens (CSS Variables)

/* Backgrounds */
--sapBackgroundColor           /* Page background */
--sapGroup_ContentBackground   /* Card/panel background */

/* Text */
--sapTextColor                 /* Primary text */
--sapContent_LabelColor        /* Labels */
--sapLink_Color                /* Links */

/* Semantic colors */
--sapPositiveColor             /* Success/green */
--sapNegativeColor             /* Error/red */
--sapCriticalColor             /* Warning/orange */
--sapInformativeColor          /* Info/blue */

Themes

Available in fundamental-styles/dist/theming/:

sap_horizon.css (default light)
sap_horizon_dark.css
sap_horizon_hcb.css (high contrast black)
sap_horizon_hcw.css (high contrast white)

Key Patterns

Always include a theme - Components need theme CSS
BEM naming - fd-component, fd-component--modifier, fd-component__element
Compact mode - Add --compact modifier for dense UIs
Accessibility - Use semantic HTML, proper ARIA attributes, aria-label for icon buttons

More Resources

🚀 NEW: Auto-generated component docs: docs/components/ (140+ components with full examples)
📘 AI Integration Guide: docs/AI_USAGE.md (how to use these docs in AI tools)
Full component list: docs/ai-component-index.md
Component schemas: docs/schemas/*.json
Utility classes: docs/utility-classes.json
Complete HTML patterns: docs/html-examples.json (table, forms, dialogs, navigation)
Modifier combinations: docs/modifier-rules.json (which modifiers conflict)
Accessibility patterns: docs/accessibility.json (ARIA for 72 components)
Design tokens: docs/design-tokens.json (1,522 CSS variables)
Visual examples: https://sap.github.io/fundamental-styles/

Updating AI Documentation

After modifying component stories, regenerate AI docs:

npm run docs:extract

This extracts HTML templates and descriptions from all .stories.js files and generates updated markdown in docs/components/.

Navigation Menu

Uh oh!

fundamental-styles

For AI Agents

Quick Lookup - "I need a..."

Packages

Quick Start

Component Classes (fd-*)

Buttons

Form Inputs

Select/Dropdown

Checkbox & Radio

Table

Dialog/Modal

Alert/Message Strip

Icons

State Classes

Utility Classes (sap-*)

Spacing

Flexbox

Display

Design Tokens (CSS Variables)

Themes

Key Patterns

More Resources

Updating AI Documentation

Uh oh!

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

fundamental-styles

For AI Agents

Quick Lookup - "I need a..."

Packages

Quick Start

Component Classes (fd-*)

Buttons

Form Inputs

Select/Dropdown

Checkbox & Radio

Table

Dialog/Modal

Alert/Message Strip

Icons

State Classes

Utility Classes (sap-*)

Spacing

Flexbox

Display

Design Tokens (CSS Variables)

Themes

Key Patterns

More Resources

Updating AI Documentation