How outsystems/outsystems-ui works
Project type and purpose
• This is an open-source UI framework/library (OutSystems UI) written in TypeScript and SCSS.
• It provides a design system, UI patterns (over 70), screen templates, and build tooling for Reactive Web and Native Mobile apps on the OutSystems platform.
• Key deliverables: a compiled NPM package (JS + CSS), documentation site, and OutSystems Service Studio integration.
File structure
• Top-level build tooling:
• gulp/ (custom Gulp tasks & specs for TS and SCSS compilation)
• gulpfile.js, package.json, tsconfig.json, typedoc.json
• GitHub Actions workflows under .github/workflows (build, release, docs, npm)
• Source code under src/:
• src/scripts/OSFramework/OSUI – core runtime, event system, feature & pattern abstractions
• src/scripts/OSFramework/OSUI/Pattern – concrete UI Patterns (Accordion, Carousel, Dropdown, …)
• src/scripts/Providers/OSUI – third-party adapters (Flatpickr, Splide, NoUISlider, VirtualSelect, etc.)
• src/scripts/OutSystems/OSUI – glue API layer for OutSystems Service Studio
• src/scss – design tokens, foundations, layouts, widgets, patterns, utilities, deprecated styles
• Documentation source:
• TypeDoc config (typedoc.json)
• markdown under src/README.md, gulp/Template/index.html
Extract architecture hints from README
• TypeScript + SCSS input → Gulp pipelines for transpilation (npm run build)
• Linting & formatting steps (npm run lint, npm run prettier)
• CI/CD builds, deploy to NPM, generate docs via TypeDoc
• Integration points:
• Published package on NPM & OutSystems Forge
• Consumed by OutSystems Service Studio at design-time
• Called via the OutSystems JS API at runtime
Main components & interactions
a. Components
1. Source modules
• Core Runtime (OSFramework/OSUI/…), Pattern Implementations, Provider Adapters
• SCSS Design System (tokens → patterns → utilities)
2. Build & Tooling
• Gulp tasks (TS transpile, SCSS compile, version bump, npm prepare)
• TypeDoc (documentation generator)
3. CI/CD (GitHub Actions)
• Release pipeline (testing → build → npm publish)
• Docs pipeline (TypeDoc → GitHub Pages)
4. Consumers
• OutSystems Service Studio (design-time drag-drop)
• Web & Mobile runtime pulling in compiled JS/CSS
• 3rd-party dependencies (Flatpickr, Splide, NoUISlider, VirtualSelect)
b. Relationships / Data flow
• Developers commit TypeScript & SCSS → CI/CD triggers → Gulp builds artifacts →
• JS/CSS package published to NPM & Forge
• Documentation generated & deployed
• At runtime, consumer apps import the JS/CSS bundle → instantiate UI Patterns →
• Core Runtime manages events, gestures, accessibility
• Pattern modules render to DOM & apply SCSS styles
• Providers supply underlying third-party library implementations
• OutSystems API layer exposes a uniform interface to Service Studio
c. Architectural patterns / design principles
• Modular architecture: Core abstractions (AbstractPattern, AbstractFeature) → concrete patterns
• Provider pattern for pluggable underlying libraries
• Separation of concerns: Runtime (events, helpers), Patterns, Styles, Build
• Convention-over-configuration: Gulp specs define naming & file conventions for auto-generation
d. Technologies & frameworks
• TypeScript (strict typing, interfaces, classes)
• SCSS (design tokens, partials, modular structure)
• Gulp (task runner), Node.js
• TypeDoc (API docs), ESLint/Prettier (lint & format)
• CI/CD: GitHub Actions, npm registry, GitHub Pages