Skip to content
Aggarly OS
  • Getting Started
    • Introduction
  • Foundations
    • Colors
    • Spacing
    • Radius
    • Typography
    • Shadows
    • Z-Index
    • Gradients
    • Tokens
    • RTL & Direction
    • Theming
  • Layout
    • Containers
    • Grid System
    • Layout Utilities
  • Components
    • Alerts
    • Avatars
    • Buttons
    • Button Group
    • Badges
    • Inputs
    • Select
    • Checkbox
    • Counters-timers
    • Radio
    • Switch
    • Stepper
    • Select-pro
    • Cards
    • Modals
    • Dropdown
    • Popover
    • Tooltip
    • Accordion
    • Breadcrumb
    • Tabs
    • Navbar
    • List Group
    • Toasts
    • Skeleton
    • Pagination
    • Progress
    • Table
    • Icons
    • Form
    • Ribbons
    • Spinner
    • Offcanvas
    • Feedback
    • Grid
    • Data UI
  • Data UI
    • Overview
  • Platform
    • Reference DataCore
  • Widgets
    • KPI
    • Analytics
    • Behavior
  • Brand
    • Logo
    • Brand Usage
Getting Started/Introduction

Aggarly Platform Design System

A unified, enterprise-grade design system powering Aggarly Platform — built for workspace admins, supervisors, educators, workspace members, and students.

TokensUtilitiesComponentsRTL + i18nAccessible UX
Getting Started
Start here if you’re contributing UI
Import the design system once, use tokens/utilities by default, and build components as composable, accessible primitives.

What is the Aggarly Platform Design System?

The design system is the shared UI foundation for Aggarly Platform. It defines visual decisions (tokens), layout patterns (utilities), and interactive building blocks (components). The goal is consistent, calm, and efficient interfaces for high-stress environments.

Colors, spacing, radius, typography, shadows, z-index. All themeable at runtime via CSS variables.

Theme-safeRuntime variablesStable semantics

Opinionated, production-ready layout helpers: stacks, spacing, flex/grid utilities, readability helpers, and docs surfaces.

No inline stylesRTL-safeReduced motion

Enterprise components that compose cleanly: forms, navigation, overlays, feedback, data display. Predictable props. Accessible defaults.

AccessibleKeyboard-firstProduction UX
Guiding rule
If you are about to hard-code a color, spacing, border, shadow, radius, or z-index — stop and use tokens/utilities instead.

Quick Start

This is the standard setup expected for every app route. Import SCSS once at the root, then use components throughout the codebase.

The design system SCSS should be loaded once in the root layout so all tokens, themes, utilities, and components are available everywhere.

Import design system SCSS
// src/app/layout.tsx (or src/app/[locale]/layout.tsx)
import "@/design-system/scss/index.scss";

Prefer importing components from the design system component modules. Keep usage consistent with docs examples.

Using design system components
import { Button } from "@/design-system/components/Button";
import { Card } from "@/design-system/components/Card";
import { InlineNotice } from "@/design-system/components/InlineNotice";

export function Example() {
  return (
    <Card title="Example" >
      <InlineNotice tone="info" title="Tip">
        Use tokens + utilities — avoid hard-coded values.
      </InlineNotice>

      <div className="flex gap-sm flex-wrap">
        <Button variant="primary" size="sm">Primary</Button>
        <Button variant="ghost" size="sm">Secondary</Button>
      </div>
    </Card>
  );
}

Tokens are defined in a single source file and compiled into CSS variables + SCSS references. After edits, rebuild tokens.

Token update workflow
// Edit the SOURCE OF TRUTH:
src/design-system/scss/tokens/source-tokens.ts

// Then regenerate token outputs:
npm run tokens:build

Folder Structure

This is the real source layout for the design system. Contributors should know where to place new components, where SCSS lives, and where tokens are defined.

Use this to quickly orient yourself. Most daily work happens in components/ and scss/components/.

Design system directory tree
E:\aggarly.com\aggarly-frontend\src\design-system
├── arct
│   ├── doc.tree
│   └── tree.sql
├── components
│   ├── data
│   │   ├── AuditLog.tsx
│   │   ├── DataToolbar.tsx
│   │   ├── EmptyState.tsx
│   │   ├── index.ts
│   │   ├── PermissionBadge.tsx
│   │   ├── StatCard.tsx
│   │   ├── StatusDot.tsx
│   │   └── Timeline.tsx
│   ├── form
│   │   ├── Form.tsx
│   │   ├── FormError.tsx
│   │   ├── FormField.tsx
│   │   ├── FormFooter.tsx
│   │   ├── FormHint.tsx
│   │   ├── FormLabel.tsx
│   │   ├── FormRow.tsx
│   │   ├── FormSection.tsx
│   │   └── index.ts
│   ├── Accordion.tsx
│   ├── Alert.tsx
│   ├── Avatar.tsx
│   ├── Badge.tsx
│   ├── Banner.tsx
│   ├── BrandMark.tsx
│   ├── Breadcrumbs.tsx
│   ├── Button.tsx
│   ├── ButtonGroup.tsx
│   ├── Callout.tsx
│   ├── Card.tsx
│   ├── Checkbox.tsx
│   ├── ConfirmDialog.tsx
│   ├── Dropdown.tsx
│   ├── Grid.tsx
│   ├── InlineNotice.tsx
│   ├── Input.tsx
│   ├── List.tsx
│   ├── Loader.tsx
│   ├── Modal.tsx
│   ├── Navbar.tsx
│   ├── Offcanvas.tsx
│   ├── Pagination.tsx
│   ├── Pill.tsx
│   ├── Popover.tsx
│   ├── Progress.tsx
│   ├── Radio.tsx
│   ├── Ribbon.tsx
│   ├── Select.tsx
│   ├── Spinner.tsx
│   ├── Stepper.tsx
│   ├── Switch.tsx
│   ├── Tabs.tsx
│   ├── Toast.tsx
│   └── Tooltip.tsx
├── hooks
│   ├── useDirection.ts
│   └── useTheme.ts
├── scss
│   ├── base
│   │   ├── index.scss
│   │   ├── _globals.scss
│   │   ├── _reset.scss
│   │   └── _typography.scss
│   ├── components
│   │   ├── index.scss
│   │   ├── _accordion.scss
│   │   ├── _alert.scss
│   │   ├── _avatar.scss
│   │   ├── _badge.scss
│   │   ├── _banner.scss
│   │   ├── _brandmark.scss
│   │   ├── _breadcrumbs.scss
│   │   ├── _button-group.scss
│   │   ├── _button.scss
│   │   ├── _callout.scss
│   │   ├── _card.scss
│   │   ├── _checkbox.scss
│   │   ├── _confirm-dialog.scss
│   │   ├── _data.scss
│   │   ├── _docs.scss
│   │   ├── _dropdown.scss
│   │   ├── _form.scss
│   │   ├── _grid.scss
│   │   ├── _inline-notice.scss
│   │   ├── _input.scss
│   │   ├── _list.scss
│   │   ├── _loader.scss
│   │   ├── _modal.scss
│   │   ├── _navbar.scss
│   │   ├── _offcanvas.scss
│   │   ├── _pagination.scss
│   │   ├── _pill.scss
│   │   ├── _popover.scss
│   │   ├── _progress.scss
│   │   ├── _radio.scss
│   │   ├── _ribbon.scss
│   │   ├── _select.scss
│   │   ├── _sessions-premium.scss
│   │   ├── _sidebar.scss
│   │   ├── _spinner.scss
│   │   ├── _stepper.scss
│   │   ├── _switch.scss
│   │   ├── _table.scss
│   │   ├── _tabs.scss
│   │   ├── _theme-preview.scss
│   │   ├── _toast.scss
│   │   ├── _token-grid.scss
│   │   ├── _tooltip.scss
│   │   └── _topbar.scss
│   ├── mixins
│   │   ├── index.scss
│   │   ├── _breakpoints.scss
│   │   ├── _glass.scss
│   │   ├── _gradient.scss
│   │   ├── _helpers.scss
│   │   ├── _hover.scss
│   │   ├── _rtl.scss
│   │   └── _theme.scss
│   ├── pages
│   │   └── _landing.scss
│   ├── themes
│   │   ├── index.scss
│   │   ├── _dark.scss
│   │   └── _light.scss
│   ├── tokens
│   │   ├── index.scss
│   │   ├── source-tokens.ts
│   │   ├── _colors.scss
│   │   ├── _radius.scss
│   │   ├── _shadows.scss
│   │   ├── _spacing.scss
│   │   ├── _typography.scss
│   │   └── _zindex.scss
│   ├── utilities
│   │   ├── index.scss
│   │   ├── _animations.scss
│   │   ├── _flex.scss
│   │   ├── _grid.scss
│   │   ├── _helpers.scss
│   │   ├── _layout.scss
│   │   ├── _lists.scss
│   │   └── _spacing.scss
│   └── index.scss
├── types
│   └── theme.ts
├── index.ts
└── README.md

How we collaborate on UI

The design system is shared infrastructure. Changes should be consistent, token-driven, and backwards compatible. Prefer adding new variants/props over breaking behavior.
  • Build a composable React component (avoid app-specific business logic inside the DS).
  • Add SCSS under scss/components with token-driven values.
  • Export from both SCSS index and TS index.
  • Create a docs page with copy-ready examples (no inline styles).
Component contribution workflow
// 1) Component implementation
src/design-system/components/MyComponent.tsx

// 2) Component styling
src/design-system/scss/components/_my-component.scss

// 3) Export SCSS (components index)
src/design-system/scss/components/index.scss
@forward "./my-component";

// 4) Export TS component
src/design-system/components/index.ts
export * from "./MyComponent";

// 5) Add docs page
src/app/[locale]/docs/components/my-component/page.tsx
  • Accessibility: keyboard navigation, correct roles/aria, focus visible behavior.
  • RTL-safe: logical CSS projects, no left/right assumptions.
  • Theme-safe: tokens/CSS variables only, no hard-coded theme colors.
  • Predictable UX: consistent dismiss rules, sizing, and alignment.
  • Reduced motion: animations must respect prefers-reduced-motion.
Tip
If a component requires interactivity in docs, keep the docs page server-rendered and add a small client wrapper (client slot) for the interactive example.

Philosophy

The design system exists to keep the UI calm, consistent, and fast to build—without sacrificing clinical-grade clarity.

Interfaces remain readable and low-noise. Visual hierarchy comes from spacing, typography, and restrained emphasis—not heavy ornamentation.

Components are built to support progress tracking, mastery, audits, and accountability patterns.

Tokens define visual decisions. Utilities encode layout patterns. Components compose those decisions into repeatable UI primitives.

Next steps

Use these pages as your day-to-day references while building Aggarly Platform UI.

Tokens, typography, spacing, theming, and RTL. Start here if you are adjusting visual language.

Copy-ready examples for dropdowns, tabs, modals, forms, navbars, feedback, and more.

Logo usage, icon rules, and asset references. Use this for marketing surfaces and product identity consistency.