# Orange Design System (ODS)
> A framework-agnostic, accessible component library built with vanilla JavaScript, CSS/SCSS, and optional React wrappers.
[](https://www.npmjs.com/package/@orangesk/orange-design-system)
[](https://nodejs.org)
## 📚 Table of Contents
- [Orange Design System (ODS)](#orange-design-system-ods)
- [📚 Table of Contents](#-table-of-contents)
- [Overview](#overview)
- [Architecture](#architecture)
- [Key Features](#key-features)
- [Installation](#installation)
- [Requirements](#requirements)
- [Quick Start](#quick-start)
- [React](#react)
- [Vanilla JavaScript](#vanilla-javascript)
- [CSS Only](#css-only)
- [Documentation](#documentation)
- [Documentation Sections](#documentation-sections)
- [Component Documentation Format](#component-documentation-format)
- [Development](#development)
- [Setup](#setup)
- [Development Server](#development-server)
- [Building](#building)
- [Testing](#testing)
- [Linting](#linting)
- [File Structure](#file-structure)
- [Contributing](#contributing)
- [Code Standards](#code-standards)
- [Component Guidelines](#component-guidelines)
- [Support](#support)
- [Resources](#resources)
- [Getting Help](#getting-help)
- [Changelog](#changelog)
## Overview
Orange Design System (ODS) is a comprehensive component library designed to work **outside of React** as the primary use case. React is used only for documentation and templating, making ODS truly framework-agnostic.
### Architecture
ODS components follow a three-layer architecture:
```
┌─────────────────────────────────────────┐
│ Your Application │
│ (React, Vue, Angular, Vanilla JS, etc.)│
└──────────────┬──────────────────────────┘
│
├─ React Components (optional)
│ └─ .tsx wrappers
│
├─ Vanilla JavaScript (core)
│ └─ .static.ts classes
│
└─ CSS/SCSS Styles
└─ BEM naming, design tokens
```
**Core:** Vanilla JavaScript + CSS/SCSS
**Optional:** React wrappers for convenient React integration
**Styling:** CSS custom properties (design tokens) with responsive breakpoints
## Key Features
✅ **Framework Agnostic** - Use in React, Vue, Angular, or vanilla JavaScript
✅ **Vanilla JavaScript Core** - No framework dependencies required
✅ **Accessible** - WCAG compliant components with ARIA attributes
✅ **Responsive** - Mobile-first design with breakpoint system
✅ **Themable** - CSS custom properties for easy customization
✅ **Type Safe** - Full TypeScript support
✅ **Performance Focused** - Lightweight, modular bundles
✅ **Well Documented** - Comprehensive documentation with live previews
## Installation
```bash
npm install @orangesk/orange-design-system
# or
yarn add @orangesk/orange-design-system
# or
pnpm add @orangesk/orange-design-system
```
### Requirements
- **Node.js:** >= 20.x
- **Package Manager:** npm, yarn, or pnpm
## Quick Start
### React
```tsx
import { Button } from "@orangesk/orange-design-system";
export default function App() {
return (
);
}
```
**Interactive Components** with JavaScript behavior:
```tsx
import { Accordion, AccordionItem } from "@orangesk/orange-design-system";
export default function MyAccordion() {
return (
Content goes here
);
}
```
The React component automatically instantiates the vanilla JavaScript class for you.
### Vanilla JavaScript
ODS components work perfectly without React:
```html
Content here
```
### CSS Only
Many components are CSS-only and don't require JavaScript:
```html
`components.css` contains component layer only. For standalone HTML usage, load `style.css` so required base tokens and CSS variables are present.
Active
Title
Description
Column 1
Column 2
Column 3
```
## Documentation
**📖 Full documentation**: [https://ods2.lb.sk](https://ods2.lb.sk)
### Documentation Sections
- **[Getting Started](https://ods2.lb.sk/getting-started)** - Installation, setup, and resources
- **[Fundamentals](https://ods2.lb.sk/fundamentals)** - Accessibility, breakpoints, color, tokens, spacing, typography
- **[Components](https://ods2.lb.sk/components)** - Full component library with examples and API docs
- **[Copy](https://ods2.lb.sk/copy)** - Tone of voice, form validation, form labels, CTA guidelines
- **[Changelog](./CHANGELOG.mdx)** - Release notes and migration guides
### Component Documentation Format
Each component page includes:
- **Basic Usage** - Getting started with the component
- **Element Types** - When to use `` vs `