@c8y/style/styles/README.md

Styles for Cumulocity IoT applications

# Styles Directory Structure

This document explains the organization of the `styles/` directory and where to add new files.

## 📁 Directory Overview

```
styles/
├── animations/          # Animation & transition styles (5 files)
├── base/               # Foundation styles (4 files)
├── components/         # UI components (62 files)
│   ├── data-display-and-visualization/
│   │   ├── lists/      # List components
│   │   ├── tables/     # Table components
│   │   ├── _range-display.scss
│   │   └── _timelines-chart.scss
│   ├── data-input/
│   │   ├── assets/     # Asset selection & management
│   │   └── _c8y-ai-chat.scss
│   ├── navigation-and-layout/
│   │   ├── action-bars/
│   │   ├── cards/
│   │   └── navigation/
│   ├── specialized/    # Cumulocity-specific components
│   ├── _markdown-content.scss
│   └── _smartrules.scss
├── core/               # Core UI primitives (18 files)
│   ├── buttons/        # Button components
│   ├── feedback/       # Alerts, badges, tooltips
│   ├── forms/          # Form controls
│   └── overlays/       # Modals, dropdowns, popovers
├── dashboard/          # Dashboard & widget styles (8 files)
├── icons/              # Icon fonts & definitions (5 files)
├── layout/             # Page layout & structure (11 files)
├── mixins/             # SCSS mixins & helpers (40 files)
├── utilities/          # Utility classes (17 files)
├── vendor/             # Third-party library styles (14 files)
│   ├── ace-editor/
│   ├── angular/
│   ├── cdk/
│   ├── datepicker/
│   ├── leaflet/
│   ├── other/
│   └── selectize/
├── _login-app.scss     # Login app entry point (standalone)
├── _mixins.scss        # Mixin imports
├── _utilities.scss     # Utility imports
└── index.scss          # Main entry point
```

## 📝 Where to Add New Files

### Components

Components are organized by **function** following the Codex documentation structure:

#### Data Display & Visualization
Add components that **display information** to users:
- Lists, tables, charts, timelines
- Data visualization widgets
- Status displays, badges
- Example location: `components/data-display-and-visualization/`

#### Data Input
Add components for **collecting user input**:
- Forms, inputs, selectors
- Asset pickers, file uploaders
- Chat interfaces, text editors
- Example location: `components/data-input/`

#### Navigation & Layout
Add components for **navigation and page structure**:
- Headers, footers, navigation bars
- Breadcrumbs, tabs, pagination
- Cards, panels, action bars
- Example location: `components/navigation-and-layout/`

#### Specialized
Add **Cumulocity-specific** components:
- Domain-specific UI (device management, alarms, etc.)
- Custom business logic components
- Internal tools and utilities
- Example location: `components/specialized/`

### Core Styles

Core styles are **primitive UI elements** used across components:

- **buttons/** - Button styles and variations
- **feedback/** - Alerts, tooltips, badges, progress bars
- **forms/** - Form controls, inputs, switches
- **overlays/** - Modals, dropdowns, popovers, wizards

### Other Directories

- **animations/** - Keyframe animations, transitions, spinners
- **base/** - Foundational styles (normalize, typography, scaffolding, print)
- **dashboard/** - Dashboard layouts and widget-specific styles
- **icons/** - Icon font definitions and icon utilities
- **layout/** - Page structure (grid, containers, drawers, split views)
- **mixins/** - Reusable SCSS mixins and functions
- **utilities/** - Utility classes (spacing, display, positioning, etc.)
- **vendor/** - Third-party library style overrides

## 🔧 Entry Points

### Main Entry Point: `index.scss`
- Primary stylesheet for the main application
- Imports all other styles in correct order
- Used by most applications

### Login App Entry Point: `_login-app.scss`
- Standalone stylesheet for the login application
- Subset of styles needed for authentication pages
- Uses `@import` syntax (separate bundle)

## 📚 File Naming Conventions

- **Partials**: Files starting with `_` (e.g., `_buttons.scss`) are partials meant to be imported
- **No underscore**: Files without `_` can be compiled standalone (e.g., `index.scss`, `welcome.scss`)
- **Lowercase with hyphens**: Use kebab-case for multi-word files (e.g., `_button-groups.scss`)
- **Prefixes**: Cumulocity-specific files use `c8y-` prefix (e.g., `_c8y-login.scss`)

## 🎯 Import Structure

Files use the modern SCSS module system:

```scss
// Variables and mixins (always first)
@use "../../variables/index" as *;
@use "../mixins/some-mixin";

// Component styles
.my-component {
  color: $brand-primary;
  @include some-mixin.helper();
}
```

**Key points:**
- Use `@use` instead of `@import` for module imports
- Variables require `as *` to access without namespace
- Mixins use namespaced access (e.g., `mixin-name.function()`)
- Path depth depends on file location (use `../` to navigate up)

## 🔄 LESS/SCSS Dual System

This codebase maintains **both LESS and SCSS** versions:

- **LESS files** are the **source of truth** (synced with develop branch)
- **SCSS files** are **converted from LESS** (migration in progress)
- Both compile to identical CSS output
- See `SYNC_WITH_DEVELOP.md` for sync instructions

## 📖 Additional Documentation

- **MIGRATION_NOTES.md** - Design token migration progress and documentation
- **SYNC_WITH_DEVELOP.md** - Instructions for syncing LESS/SCSS after merges
- **packages/style/README.md** - Package-level documentation
- **REORGANIZATION_PLAN.md** - Historical record of structure changes (if exists)

## 🚀 Quick Start

**Adding a new component:**

1. Choose the appropriate directory based on component function
2. Create a partial file with `_` prefix (e.g., `_my-component.scss`)
3. Add documentation header with intentionally hardcoded values
4. Import variables and needed mixins
5. Add the import to `index.scss` in the correct section
6. Verify compilation: `npx sass packages/style/styles/index.scss output.css`

**Example:**

```scss
// styles/components/data-display-and-visualization/_my-chart.scss
@use "../../../variables/index" as *;

/**
 * My Chart - Custom chart component
 *
 * Note: Uses $size-* tokens for spacing.
 *
 * Intentionally hardcoded values:
 * - Border widths (1px): Standard borders
 * - Z-index (10): Stacking order
 */

.my-chart {
  padding: $size-16;
  border: 1px solid $component-border-color;
}
```

Then add to `index.scss`:
```scss
// In the Data Display & Visualization section
@use 'components/data-display-and-visualization/_my-chart';
```

---

**Last Updated:** December 16, 2025
**Maintained by:** Cumulocity UI Team