Design System + AI = ❤️

We've enhanced the Spiris Design System with structured Markdown documentation specifically designed for AI-assisted development. These files provide comprehensive, machine-readable reference materials for components, enabling developers using GitHub Copilot, Claude, ChatGPT, and other AI coding assistants to get accurate, up-to-date implementation guidance directly in their workflow. The documentation includes detailed component APIs, usage patterns, accessibility requirements, and code examples—all formatted for optimal LLM comprehension. This means faster development, fewer errors, and better adherence to design system standards when building with AI assistance.

You can find the Markdown docs in the docs directory of the npm package after you have installed the designsystem package.

Below you can find a migrated version of the index.md file which links to all documentation files (you need GitHub access to view the real files):

Spiris Design System - Component Documentation Index

Welcome to the Spiris Design System component documentation. This index provides quick access to all component guides.

📚 About This Documentation

This documentation provides implementation guides, code examples, and best practices for all components in the Spiris Design System. Each guide includes:

Component overview and use cases

HTML code examples

CSS class reference

Accessibility guidelines

JavaScript implementation examples

Best practices

⚠️ Important: JavaScript Not Included in Package

The Spiris Design System npm package contains only CSS and SVG assets. JavaScript code examples in this documentation are provided as reference implementations to demonstrate interactive behavior. You are responsible for implementing your own JavaScript based on these examples or using a framework of your choice.

What's included in the npm package:

✅ CSS files (compiled and source SCSS)

✅ SVG icons and assets

✅ Design tokens

What's NOT included:

❌ JavaScript files

❌ Framework-specific components (React, Vue, Angular, etc.)

If a component requires JavaScript for interactivity (modals, dropdowns, tooltips, etc.), you must implement the behavior yourself using the HTML structure and CSS classes provided.

🚀 Getting Started

Before using components, ensure you've:

1. Installed the design system

2. Included the appropriate CSS file

3. Reviewed the browser support policy

📖 Component Categories

> Each guide is a standalone, per-component page named after the component.

Buttons & Actions

Buttons - Primary, secondary, and tertiary buttons

Icon Button - Icon-only buttons

Segmented Button Group - Grouped, toolbar, and justified button sets

Dropdown Button - Button that opens a command menu

Split Button - Primary action plus a dropdown

Chips - Facet / filter chips

Toggle - On/off switch

Core Components

Alert - Important messages and notifications

Notification badges - Status indicators and counters

Label badges - Status indicators and counters

Card - Single hero / dashboard card

Form Elements

Forms - Form layouts, groups, and fieldsets

Input Fields & Textareas - Text inputs, textareas, select fields, and input groups

Checkboxes - Checkbox controls

Radio Buttons - Radio controls

Dropdown - Select-style dropdown field

Combobox - Searchable select dropdown and combogrid

Combobox Multi Select - Multi-select combobox with tag/chip display

Datepicker - Date selection component

Timepicker - Time selection component

Search Fields - Search input fields

Upload & File - Drop area and uploaded-file rows

Form Validation - Error states and inline validation

Layout & Grid

Grids - Responsive 12-column grid system with auto-layout, alignment, and reordering

Helper Classes - Utility classes for spacing, display, flex, typography, and more

Typography - Text styles, headings, and typographic hierarchy

Theming & Customisation

CSS Properties - Complete reference of all CSS variables including colours, spacing, typography, elevation, and component tokens

Design Tokens - Token families and how they map to CSS custom properties

Deprecations - Deprecated features and migration guides for upcoming breaking changes

Navigation

Header - Top navigation bar

Side Menu - Vertical side navigation

Breadcrumbs - Hierarchical page trail

Tabs - Tabbed content navigation

Pagination - Page navigation for lists and search results

Wizard - Multi-step process navigation

Interactive Components

Modals - Dialog boxes and modal windows

Drawers - Slide-out side panels

Popover - Contextual popup elements

Tooltips - Hover tooltips and hints

Toasts - Temporary notification messages

Progress & Feedback

Progress Bar - Determinate horizontal progress bar

Progress Circle - Circular progress indicator

Spinner - Indeterminate loading spinner

Stepper - Horizontal and vertical step progress indicators

Data Display

Table - Data tables with sorting, filtering, and row states

Dropdown Lists - Dropdown list popup for Dropdown button, Split button, and Combobox

List Groups - Styled in-page content lists

Accordion - Collapsible content lists

Panels - Content containers with headers and footers

Media & Icons

Icons - Complete icon library including general, functional, flag, and status icons

Images - Image handling and responsive images

Favicons - Favicon implementation guide

Developer Tooling

Figma MCP - Figma Model Context Protocol integration reference

🎨 Design Tokens

The design system uses design tokens for consistent styling:

Colors and themes

Typography scale and font families

Spacing and sizing units

Border radius and shadows

Breakpoints and grid specifications

📱 Responsive Design

All components are built mobile-first and support responsive breakpoints:

XS (<550px) - Mobile phones

S (≥769px) - Large phones and small tablets

M (≥992px) - Tablets

L (≥1280px) - Small laptops

XL (≥1440px) - Laptops and desktops

XXL (≥1680px) - Large desktops

♿ Accessibility

The design system follows WCAG 2.1 AA standards. Each component guide includes:

ARIA attribute requirements

Keyboard navigation support

Screen reader considerations

Color contrast guidelines

Focus management

🔧 JavaScript Requirements

Some components require JavaScript:

No JS Required: Alerts, Badges, Buttons (basic), Forms (basic), Grids, Typography, Helper Classes, Panels, Breadcrumbs, Pagination

Optional JS: Button groups, Pills, Segmented button group (for toggle state and the animated indicator)

Required JS: Dropdowns, Modals, Drawers, Tabs, Tooltips, Popovers, Toasts, Navigation (responsive), Datepicker, Timepicker, Combobox, File upload (drag & drop)