Matios UI Framework
Zero-dependency UI framework built with pure CSS and JavaScript.
Mode + accent theming · High-contrast support · 85+ components · 316 icons
· Español
---
## Why Matios UI
Most UI libraries are tied to a framework, overloaded with dependencies, or difficult to adapt to real projects.
Matios UI takes a different approach:
| | |
|---|---|
| **Zero dependencies** | Pure CSS + plain JavaScript — no build step required |
| **Framework-agnostic** | Works in static sites, server-rendered apps, legacy systems, and microfrontends |
| **Self-contained components** | Each component ships with its own `.css`, `.js`, `.md` docs, and `demo.html` |
| **Real theming** | Mode + accent model with full high-contrast support |
| **Easy to inspect** | Open, readable source — no minified bundles to reverse-engineer |
---
## Install
**CDN (no build, no install)** — the whole framework in two tags:
```html
```
**npm** — for bundlers (Vite, webpack, etc.):
```bash
npm install @matios/ui
```
```js
import "@matios/ui"; // registers window.MTS (all components)
import "@matios/ui/css"; // base + component styles
import "@matios/ui/themes/matios-ui-accent-violet.css";
new MTS.Button("#btn", { label: "Hello", variant: "primary" });
```
**TypeScript** — type declarations ship with the package (`dist/matios-ui.d.ts`).
`MTS`, every component class and its options are typed out of the box, for both
`import MTS from "matios-ui"` and the global `window.MTS`.
> The `dist/` bundles and `.d.ts` are produced by `npm run build` (esbuild). The
> source stays a zero-dependency, no-build set of `window.MTS` scripts — you can
> also drop the individual component files in via `
```
---
## Running locally
The framework has **no build step**, but the explorer and demos load files over HTTP (component docs, demos, mock data) — so serve the folder instead of opening files directly via `file://`.
**VS Code + Live Server (recommended)**
1. Install the **Live Server** extension by *Ritwick Dey* — [marketplace](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer).
2. Right-click `index.html` → **Open with Live Server**.
3. The browser opens at `http://127.0.0.1:5500` with live reload on save.
**Or any static server**
```bash
npx serve .
# or
python -m http.server 5500
```
---
## Theming
Matios UI uses a **mode + accent** model controlled by HTML attributes.
### Modes
```html
```
### Accents
```html
```
Available accents: `violet` · `olive` · `blue` · `corporate` · `navy` · `emerald` · `petrol`
> `high-contrast` is a standalone mode — it does not require an accent.
---
## Component Groups
### Forms
`Button` · `Input` · `Select` · `Checkbox` · `Radio` · `Toggle` · `Slider` · `TagInput` · `Rating` · `DatePicker` · `FileUpload` · `NumberInput` · `PhoneInput` · `NationalId` · `ColorPicker` · `RichEditor` · `FormLayout` · `FormGuard` · `CopyButton` · `ConfirmButton` · `Label` · `PasswordStrength` · `TransferList` · `Validate`
### Navigation
`Tabs` · `Accordion` · `Breadcrumb` · `Stepper` · `StepProgress` · `Drawer` · `Dropdown` · `PanelDropdown` · `Pagination` · `CommandPalette` · `ContextMenu` · `SideNav` · `TabBar` · `Topbar` · `Menu`
### Overlays
`Alert` · `Badge` · `Tooltip` · `Modal` · `Popover` · `Toast` · `Progress` · `Skeleton` · `Spinner` · `Lightbox`
### Display
`Avatar` · `Card` · `KPICard` · `EmptyState` · `Timeline` · `SortableList` · `Countdown` · `RatingReview` · `Tree` · `ImageGallery` · `VirtualList` · `MarkdownViewer`
### Layout
`Grid` · `Scroll` · `Splitter` · `ScrollSpy` · `IntersectionReveal`
### Data
`Table` · `DataTable` (widget)
### Utilities
`HttpClient` · `CodeBlock` · `DevPanel` · `DiagnosticsPanel` · `JsonViewer` · `SessionTimeout` · `PageLoader` · `Sanitize` · `Browser`
### Icons
**316 icons** — outline / filled · semantic color variants · size variants · spin animation
```html
```
---
## Widgets
Higher-level components composed from primitives.
| Widget | Description |
|---|---|
| **DataTable** | Full-featured data grid — sort, filter, pagination, plugins (DocumentManager, Toolbar, ColumnVisibility, ExpandRow, Filter) |
| **Calendar** | Month / week / day / agenda views with event management, drag & drop and async datasource |
| **Boards** | `GanttChart` (SVG Gantt + WBS, baseline, undo/redo) · `Kanban` · `SprintBoard` — each with an FE↔BE contract doc |
| **Dashboard** | Admin template — _in development_ |
---
## Component Structure
Every component follows the same pattern:
```
matios-ui-xxx/
├── matios-ui-xxx.css
├── matios-ui-xxx.js
├── matios-ui-xxx.md
└── demo.html
```
---
## Apps Showcase
`apps-showcase/` contains complete, realistic UI screens built exclusively with Matios UI components.
**Groups available:**
- **Authentication** — login, forgot-password, reset-password, verify-email, workspace-selector, session-expired, access-denied, accept-invitation
- **Onboarding** — signup-basic, signup-with-company, invite-team, onboarding-complete
- **Account** — profile-overview, security-settings
- **Settings** — workspace-settings, security-policies
- **Support** — ticket-inbox, ticket-detail, ticket-resolution
- **Productivity** — task-board, calendar-planner, task-detail
- **Notifications** — notification-center, activity-feed
- **Admin** — members-list, member-detail, invite-member, access-review, role-detail
- **Billing** — current-plan, invoice-history, payment-methods, usage-and-limits, plan-change-preview
- **Developers** — api-keys, webhooks
- **Integrations** — integrations-hub, integration-detail, connect-provider, sync-history
- **Documents** — recent-files, file-preview, share-dialog
- **Search** — global-search, search-results
- **System** — error-404, error-403, error-500, maintenance-mode, empty-workspace
---
## Entry Points
| File | Purpose |
|---|---|
| `index.html` | Main framework explorer |
| `themes/demo.html` | Mode + accent theming preview |
| `icons/demo.html` | Full icon catalog |
| `apps-showcase/index.html` | Showcase screen catalog |
| `/demo.html` | Grouped component navigation |
| `/demo.html` | Isolated component demo |
---
## Events
Components emit events using the `mts:*` namespace:
```javascript
document.getElementById('my-calendar')
.addEventListener('mts:calendar:eventDrop', function(e) {
console.log(e.detail);
});
```
---
## Design Principles
- Use Matios components first — avoid ad-hoc UI when a real component exists
- Each component is self-contained and independent
- Demos are consistent, realistic, and inspectable
- Source is readable — no build pipeline required
- Naming, grouping, and structure follow the same conventions throughout
See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the full coding conventions, rules, and development flow.
---
## Status
Matios UI is **production-ready** as a framework — coherent structure, consistent theming, full component coverage, and real documentation per component.
---
## Browser support
Modern evergreen browsers. The codebase targets **ES2020** (optional chaining `?.` and nullish `??`); it uses no newer
syntax or APIs, no transpiler and no polyfills.
| Browser | Minimum |
|---|---|
| Chrome / Edge | 80+ |
| Firefox | 78+ |
| Safari | 14+ |
Internet Explorer is not supported. The bundles published to npm (`dist/` — generated by `npm run build`, not committed to the repo) are pinned to this baseline via the esbuild target.
---
## Versioning
Matios UI follows [Semantic Versioning](https://semver.org/). The framework is versioned as a single unit (`MAJOR.MINOR.PATCH`);
component-level changes are tracked by date in each component's `.md`. See [`CHANGELOG.md`](./CHANGELOG.md) for releases
and [`RELEASING.md`](./RELEASING.md) for the release process.
---
## Documentation
- Every component has its own `.md` (Installation · Usage · Options · API · Events · CSS Variables · Accessibility · Changelog) next to its `.css`/`.js`/`demo.html`.
- Each component group has a `README.md` index listing its components.
## Contributing
See [`CONTRIBUTING.md`](./CONTRIBUTING.md) and the [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md). Issues and pull requests are welcome.
## License
[MIT](./LICENSE) © Matios SpA.
## 💛 Support
Matios UI is free and MIT-licensed. If it saves you time, you can support its ongoing development:
[](https://ko-fi.com/gcontrerasgomez)
🪙 Donate with crypto
| Network | Address |
|---|---|
| **Ethereum / EVM** (ETH, USDC, …) | `0x5ea6F302Fb8a9865540FfCC42F7264c996532dC3` |
| **Bitcoin** (native SegWit) | `bc1qv43are3facy6lyuzp5qpdqpt8x7tcz2cx3aspe` |
| **Solana** (SOL, SPL) | `BYtfMGEoxBLf5DMPoLyebUJpEh1hW9jGEvjiaEiuRmjw` |
| **TRON** (USDT-TRC20) | `TFHuJKpPNZcdEPsfCknDpvY6CzQbpWYGUv` |
Every contribution helps keep the project maintained — thank you 🙏
## Español
¿Prefieres español? Lee la [guía de inicio en español](./README.es.md).
---
Matios UI Framework
Pure CSS · Pure JavaScript · Real structure.