llms.txt
Compare with other sites' llms.txt files →# modest-ui
> A minimal, themeable CSS component library.
IMPORTANT: The npm package is "mdst-ui", NOT "modest-ui". The name "modest-ui"
on npm is an UNRELATED Vue library — do not install it. This package is named
"mdst-ui" to match its class/token prefix (.mdst-ui, --mdst-*). Whenever a
human says "modest-ui", the package to install is "mdst-ui".
- Version: 2.0.1 (this file describes v2; class names differ from v1)
- Package (npm): mdst-ui
- Docs: https://modest-ui.com
- GitHub: https://github.com/thisismodest/modest-ui
- License: MIT
## Installation
CDN (pin the major version so markup and CSS match):
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/mdst-ui@2/dist/modest-ui.min.css" />
npm:
npm install mdst-ui # NOT "npm install modest-ui"
Import (bundled):
@import "mdst-ui/dist/modest-ui.css";
Cherry-pick (tokens first):
@import "mdst-ui/base/tokens.css";
@import "mdst-ui/components/button/button.css";
modest-ui is CSS only. JavaScript shown in the docs is example code for
behaviour you own (switching tabs, showing a toast, revealing a password).
## Rules for writing modest-ui markup
1. Put `class="mdst-ui"` on `<body>` (or a wrapper) and write semantic HTML.
Bare elements inside it are styled with no classes.
2. Add a modifier class only for a variant: `<button class="mdst-button--solid">`.
Modifiers work on bare elements without the base class.
3. Use the base class (`.mdst-button`, `.mdst-input`) outside `.mdst-ui`, or for
components that have no native element (card, tag, tabs, toast…).
4. Drive runtime state with data attributes (`data-state="active"`, `"visible"`,
`"completed"`), and ARIA where it exists (`aria-pressed`, `aria-invalid`,
`aria-selected`, `aria-disabled`). Never use data attributes for colour or size.
5. Theme with `--mdst-*` tokens. Don't restyle components to change colours.
6. Put your own layout CSS outside any cascade layer; it always wins.
7. Every `<input>` takes the same class, `.mdst-input`, and is styled by its
`type`: text, email, number, date, checkbox, radio, range, file, color.
A checkbox with `role="switch"` is drawn as a toggle. Labels need no
class. Only password and OTP have a wrapper (`.mdst-password-input`,
`.mdst-otp-input`), and the inputs inside take no element class.
## Naming
BEM with the `mdst-` prefix:
- Block: `.mdst-card`
- Element: `.mdst-card__header`, `.mdst-tabs__panel`
- Modifier: `.mdst-card--sm`, `.mdst-card__header--borderless`
Shared modifier vocabulary:
- Status: `--success`, `--info`, `--warning`, `--danger` (and `--muted`)
- Fill and edge: `--solid`, `--subtle`, `--borderless`
- Size: `--sm`, `--lg`
- Direction: `--start`, `--end` (never left/right)
## Classless elements
Styled automatically inside `.mdst-ui`: button, input (every type, as with
`.mdst-input`), input[type="checkbox"][role="switch"] (a toggle), textarea,
select, form, fieldset, legend, label, details, dialog, table, progress,
meter, code, pre, h1–h6, p, a, strong, em, small, mark, kbd, abbr[title], del,
ins, s, cite, samp, var, sub, sup, blockquote, hr, ul, ol, li.
Class-only components: avatar, badge, banner, breadcrumbs, card, drawer,
otp-input, password-input, popover, radio cards, skeleton, spinner, stepper,
tabs, tag, toast, toolbar, tooltip, utilities.
## Behaviour to know
- Cascade layer: everything is in `@layer mdst-ui`. Any CSS outside a layer
beats it. To order against other layers: `@layer reset, mdst-ui, utilities;`
- Flow spacing: children of plain containers inside `.mdst-ui` (the root and
unclassed main, section, article, div, form, fieldset, …) are spaced by
`--mdst-flow-space`. Give a container a class or an inline style to lay it
out yourself.
- Dark mode is opt-in: `:root { color-scheme: light dark; }` follows the
system, `color-scheme: dark` forces it. Without it pages stay light.
- Focus: one keyboard ring for everything (`--mdst-focus-ring`,
`--mdst-focus-offset`).
- Right-to-left: components use logical properties and mirror in `dir="rtl"`.
- The reset only applies inside `.mdst-ui`.
---
## Design Tokens
Override these custom properties on `:root` (or any element) to theme modest-ui.
### Colors
| Token | Value |
| -------------------- | ------- |
| --mdst-color-fg | #000 |
| --mdst-color-bg | #fff |
| --mdst-color-border | #000 |
| --mdst-color-muted | #666 |
| --mdst-color-subtle | #f5f5f5 |
| --mdst-color-focus | #000 |
| --mdst-color-danger | #dc2626 |
| --mdst-color-warning | #b45309 |
| --mdst-color-success | #15803d |
### Typography
| Token | Value |
| ------------------ | ---------------------------------------------------------------------------- |
| --mdst-font-sans | system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif |
| --mdst-font-mono | ui-monospace, "SF Mono", Consolas, "Liberation Mono", Menlo, monospace |
| --mdst-line-height | 1.5 |
### Semantic font roles
| Token | Value |
| ---------------- | --------------------- |
| --mdst-font-text | var(--mdst-font-sans) |
| --mdst-font-ui | var(--mdst-font-sans) |
### Font sizes
| Token | Value |
| ---------------- | -------- |
| --mdst-text-xs | 0.75rem |
| --mdst-text-sm | 0.875rem |
| --mdst-text-base | 1rem |
| --mdst-text-lg | 1.125rem |
| --mdst-text-xl | 1.25rem |
### Spacing
| Token | Value |
| --------------- | --------- |
| --mdst-space-px | 0.0625rem |
| --mdst-space-1 | 0.25rem |
| --mdst-space-2 | 0.5rem |
| --mdst-space-3 | 0.75rem |
| --mdst-space-4 | 1rem |
| --mdst-space-5 | 1.25rem |
| --mdst-space-6 | 1.5rem |
| --mdst-space-8 | 2rem |
### Semantic spacing aliases
| Token | Value |
| --------------- | ------------------- |
| --mdst-space-xs | var(--mdst-space-1) |
| --mdst-space-sm | var(--mdst-space-2) |
| --mdst-space-md | var(--mdst-space-4) |
| --mdst-space-lg | var(--mdst-space-6) |
| --mdst-space-xl | var(--mdst-space-8) |
### Flow
| Token | Value |
| ----------------- | ----- |
| --mdst-flow-space | 1em |
### Focus
| Token | Value |
| ------------------- | ----- |
| --mdst-focus-offset | 0px |
### Border
| Token | Value |
| ------------------- | -------- |
| --mdst-radius | 0 |
| --mdst-border-width | 0.0625em |
### Transitions
| Token | Value |
| ---------------------- | -------------- |
| --mdst-transition-fast | 50ms ease-out |
| --mdst-transition | 100ms ease-out |
| --mdst-transition-slow | 200ms ease-out |
### Depth
| Token | Value |
| ---------------- | ------------------------------------- |
| --mdst-shadow-sm | 0 0.125rem 0.375rem rgb(0 0 0 / 0.15) |
| --mdst-shadow | 0 0.25rem 0.75rem rgb(0 0 0 / 0.2) |
| --mdst-backdrop | rgb(0 0 0 / 0.4) |
| --mdst-z-overlay | 1000 |
### State
| Token | Value |
| ----------------------- | ----- |
| --mdst-disabled-opacity | 0.5 |
### Optional tokens
Not set by default; set them to change behaviour everywhere.
| Token | Effect |
| --- | --- |
| `--mdst-focus-ring` | Replaces the keyboard focus ring, e.g. `3px dashed hotpink`, or `none` |
| `--mdst-color-info` | Colour for `--info` variants (defaults to the text colour) |
| `--mdst-button-hover-shadow` | Button hover (default: an inset ring in the text colour), or `none` |
### Button variables
Set on a button, a class, or a container to make your own variant:
| Variable | Default |
| --- | --- |
| `--mdst-button-tone` | `--mdst-color-fg` (text, and the fill of solid buttons) |
| `--mdst-button-bg` | `--mdst-color-bg` |
| `--mdst-button-fg` | the tone |
| `--mdst-button-border` | `--mdst-color-border` |
---
## Components
---
### Avatar `.mdst-avatar`
Circular or square avatar containers for user images and initials. Supports multiple sizes and grouping with overlap.
Classes:
- `.mdst-avatar`
- `.mdst-avatar-group`
- `.mdst-avatar--lg`
- `.mdst-avatar--sm`
- `.mdst-avatar--square`
- `.mdst-avatar--xl`
```html
<!-- Avatar with image -->
<span class="mdst-avatar">
<img src="avatar.jpg" alt="User" />
</span>
<!-- Avatar with initials -->
<span class="mdst-avatar">AB</span>
<!-- Sizes -->
<span class="mdst-avatar mdst-avatar--sm">AB</span>
<span class="mdst-avatar mdst-avatar--lg">AB</span>
<span class="mdst-avatar mdst-avatar--xl">AB</span>
<!-- Square variant -->
<span class="mdst-avatar mdst-avatar--square">
<img src="avatar.jpg" alt="User" />
</span>
<!-- Avatar group -->
<div class="mdst-avatar-group">
<span class="mdst-avatar">
<img src="user1.jpg" alt="User 1" />
</span>
<span class="mdst-avatar">
<img src="user2.jpg" alt="User 2" />
</span>
<span class="mdst-avatar">+3</span>
</div>
```
---
### Badge `.mdst-badge`
Small count and notification indicators. Supports solid, subtle, and dot variants with optional absolute positioning for overlays.
Classes:
- `.mdst-badge`
- `.mdst-badge--danger`
- `.mdst-badge--dot`
- `.mdst-badge--info`
- `.mdst-badge--lg`
- `.mdst-badge--muted`
- `.mdst-badge--sm`
- `.mdst-badge--solid`
- `.mdst-badge--subtle`
- `.mdst-badge--success`
- `.mdst-badge--top-end`
- `.mdst-badge--warning`
```html
<!-- Default badge -->
<span class="mdst-badge">3</span>
<!-- Variants -->
<span class="mdst-badge mdst-badge--solid">12</span>
<span class="mdst-badge mdst-badge--subtle">New</span>
<span class="mdst-badge mdst-badge--dot"></span>
<!-- Status colors -->
<span class="mdst-badge mdst-badge--danger mdst-badge--solid">5</span>
<span class="mdst-badge mdst-badge--success">✓</span>
<span class="mdst-badge mdst-badge--warning">!</span>
<span class="mdst-badge mdst-badge--muted">0</span>
<!-- Sizes -->
<span class="mdst-badge mdst-badge--sm">3</span>
<span class="mdst-badge mdst-badge--lg">12</span>
<!-- Positioned on an element -->
<div style="position: relative; display: inline-flex;">
<button class="mdst-button">Inbox</button>
<span class="mdst-badge mdst-badge--solid mdst-badge--danger mdst-badge--top-end">7</span>
</div>
<!-- Dot indicator -->
<span class="mdst-badge mdst-badge--success mdst-badge--dot"></span>
```
---
### Banner `.mdst-banner`
Full-width message strip for cookie consent, alerts, and announcements. Sits in the page flow, sticks to the top or bottom of a section, or fixes to the viewport. Status variants are modifier classes; visibility is driven by data-state.
Classes:
- `.mdst-banner`
- `.mdst-banner__actions`
- `.mdst-banner__close`
- `.mdst-banner__content`
- `.mdst-banner--border-bottom`
- `.mdst-banner--border-end`
- `.mdst-banner--border-start`
- `.mdst-banner--border-top`
- `.mdst-banner--borderless`
- `.mdst-banner--bottom`
- `.mdst-banner--danger`
- `.mdst-banner--end`
- `.mdst-banner--fixed`
- `.mdst-banner--info`
- `.mdst-banner--sm`
- `.mdst-banner--start`
- `.mdst-banner--success`
- `.mdst-banner--top`
- `.mdst-banner--warning`
```html
<!-- In the flow of the page -->
<section class="mdst-banner mdst-banner--info" aria-label="Announcement">
<div class="mdst-banner__content">Scheduled maintenance on Sunday.</div>
<button class="mdst-banner__close" aria-label="Dismiss">✕</button>
</section>
<!-- Sticky to the top of a scrolling section -->
<section style="overflow-y: auto">
<div class="mdst-banner mdst-banner--top mdst-banner--border-bottom">...</div>
...
</section>
<!-- Fixed to the bottom of the viewport (cookie consent) -->
<section class="mdst-banner mdst-banner--fixed mdst-banner--bottom"
data-state="visible" aria-label="Cookie consent">
<div class="mdst-banner__content">We use analytics cookies.</div>
<div class="mdst-banner__actions">
<button class="mdst-button mdst-button--sm">Reject</button>
<button class="mdst-button mdst-button--sm mdst-button--solid">Accept</button>
</div>
</section>
<!-- Compact card fixed to the bottom-right corner -->
<section class="mdst-banner mdst-banner--sm mdst-banner--fixed mdst-banner--bottom mdst-banner--end"
data-state="visible" aria-label="Cookie consent">...</section>
<!-- Edge-to-edge fixed banner -->
<div class="mdst-banner mdst-banner--fixed mdst-banner--top" style="--mdst-banner-offset: 0">...</div>
<!-- Example JS -->
<script>
function showBanner(el) {
el.setAttribute("data-state", "visible");
}
function hideBanner(el) {
el.setAttribute("data-state", "hidden");
}
</script>
```
---
### Breadcrumbs `.mdst-breadcrumbs`
Navigation breadcrumb trail with separator support. Works classless via aria-label or with explicit class.
Classes:
- `.mdst-breadcrumbs`
- `.mdst-breadcrumbs--arrow`
- `.mdst-breadcrumbs--sm`
```html
<!-- Class-based breadcrumbs -->
<nav class="mdst-breadcrumbs" aria-label="Breadcrumb">
<ol>
<li><a href="#home">Home</a></li>
<li><a href="#products">Products</a></li>
<li><span aria-current="page">Widget</span></li>
</ol>
</nav>
<!-- Arrow separator -->
<nav class="mdst-breadcrumbs mdst-breadcrumbs--arrow" aria-label="Breadcrumb">
<ol>
<li><a href="#home">Home</a></li>
<li><span aria-current="page">Page</span></li>
</ol>
</nav>
<!-- Compact -->
<nav class="mdst-breadcrumbs mdst-breadcrumbs--sm" aria-label="Breadcrumb">
<ol>
<li><a href="#home">Home</a></li>
<li><span aria-current="page">Page</span></li>
</ol>
</nav>
```
---
### Button `.mdst-button`
Button with solid, borderless, and danger variants, toggle and disabled states, and three sizes. Variants are just variables, so you can make your own.
Classes:
- `.mdst-button`
- `.mdst-button--borderless`
- `.mdst-button--danger`
- `.mdst-button--lg`
- `.mdst-button--sm`
- `.mdst-button--solid`
```html
<button class="mdst-button">Default</button>
<button class="mdst-button mdst-button--solid">Inverted</button>
<button class="mdst-button mdst-button--borderless">Ghost</button>
<button class="mdst-button mdst-button--sm">Small</button>
<button class="mdst-button mdst-button--lg">Large</button>
<!-- Danger is a colour: combine it with any variant -->
<button class="mdst-button mdst-button--danger mdst-button--solid">Delete</button>
<!-- Toggle buttons -->
<button class="mdst-button" aria-pressed="true">Bold</button>
<!-- Links can't be disabled: drop the href, keep role="link", add aria-disabled -->
<a class="mdst-button" role="link" aria-disabled="true">Unavailable</a>
/* Hover: any box-shadow, or none */
:root { --mdst-button-hover-shadow: none; }
/* Prefer an underline? Add your own rule */
.mdst-ui button:hover { text-decoration: underline; }
<!-- Your own variant: set the variables -->
.btn-brand { --mdst-button-tone: #4338ca; }
<button class="mdst-button mdst-button--solid btn-brand">Brand</button>
```
---
### Card `.mdst-card`
A bordered container for grouping content with optional header, body, and footer sections.
Classes:
- `.mdst-card`
- `.mdst-card__body`
- `.mdst-card__footer`
- `.mdst-card__header`
- `.mdst-card--borderless`
- `.mdst-card--flush`
- `.mdst-card--interactive`
- `.mdst-card--sm`
- `.mdst-card__footer--borderless`
- `.mdst-card__header--borderless`
```html
<!-- Basic card -->
<div class="mdst-card">
<div class="mdst-card__body">Content</div>
</div>
<!-- With header, body, and footer -->
<div class="mdst-card">
<div class="mdst-card__header">Title</div>
<div class="mdst-card__body">Content goes here.</div>
<div class="mdst-card__footer">
<button class="mdst-button mdst-button--sm">Action</button>
</div>
</div>
<!-- Interactive (hover state) -->
<div class="mdst-card mdst-card--interactive">
<div class="mdst-card__body">Clickable card</div>
</div>
<!-- Compact padding -->
<div class="mdst-card mdst-card--sm">
<div class="mdst-card__body">Tight content</div>
</div>
<!-- Flush body (no body padding, for tables/images) -->
<div class="mdst-card mdst-card--flush">
<div class="mdst-card__header">Table card</div>
<div class="mdst-card__body">
<table class="mdst-table">...</table>
</div>
</div>
<!-- Borderless header (no bottom border) -->
<div class="mdst-card">
<div class="mdst-card__header mdst-card__header--borderless">Title</div>
<div class="mdst-card__body">Content</div>
</div>
<!-- Borderless footer (no top border) -->
<div class="mdst-card">
<div class="mdst-card__body">Content</div>
<div class="mdst-card__footer mdst-card__footer--borderless">
Tags or metadata here
</div>
</div>
```
---
### Checkbox `.mdst-input`
Checkbox, and a toggle switch for checkboxes with role="switch". Label support, checked, and disabled states.
Classes:
- `.mdst-input`
- `.mdst-input--pill`
```html
<!-- With label (recommended) -->
<label>
<input type="checkbox" class="mdst-input" />
Label text
</label>
<!-- Standalone -->
<input type="checkbox" class="mdst-input" />
<!-- States -->
<input type="checkbox" class="mdst-input" checked />
<input type="checkbox" class="mdst-input" disabled />
<!-- Toggle -->
<input type="checkbox" class="mdst-input" role="switch" />
<input type="checkbox" class="mdst-input" role="switch" checked />
<input type="checkbox" class="mdst-input" role="switch" disabled />
<!-- Toggle rounded -->
<input type="checkbox" class="mdst-input mdst-input--pill" role="switch" />
<input type="checkbox" class="mdst-input mdst-input--pill" role="switch" checked />
```
---
### Code `.mdst-code`
Inline code component for displaying code snippets within text.
Classes:
- `.mdst-code`
```html
<p>Use <code class="mdst-code">const x = 1</code> to declare a variable.</p>
```
---
### Color `.mdst-input`
Native colour input drawn as a round or square swatch.
Classes:
- `.mdst-input`
- `.mdst-input--square`
```html
<input type="color" class="mdst-input" value="#000000" />
<!-- Square, following --mdst-radius -->
<input type="color" class="mdst-input mdst-input--square" value="#F4E3C1" />
<!-- With the hex value beside it -->
<div style="display: flex; gap: 0.5rem; align-items: center">
<input type="color" class="mdst-input" value="#4A3F1F" />
<input type="text" class="mdst-input" value="#4A3F1F" style="width: 7rem" />
</div>
```
---
### Date & time `.mdst-input`
Date, time, datetime-local, month, and week inputs, styled to match the text fields. The pickers are the browser's own.
Classes:
- `.mdst-input`
```html
<input type="date" class="mdst-input" />
<input type="time" class="mdst-input" />
<input type="datetime-local" class="mdst-input" />
<input type="month" class="mdst-input" />
<input type="week" class="mdst-input" />
<!-- Limit the range -->
<input type="date" class="mdst-input" min="2026-10-01" max="2026-10-31" />
```
---
### Details `.mdst-details`
Expandable details/accordion component with section variants.
Classes:
- `.mdst-details`
- `.mdst-details--borderless`
- `.mdst-details--section`
- `.mdst-details--sm`
```html
<!-- Basic details -->
<details class="mdst-details">
<summary>Click to expand</summary>
<p>Content goes here.</p>
</details>
<!-- Open by default -->
<details class="mdst-details" open>
<summary>Already open</summary>
<p>Content goes here.</p>
</details>
<!-- Section variant -->
<details class="mdst-details mdst-details--section">
<summary>Section Title</summary>
<p>Content goes here.</p>
</details>
<!-- Exclusive open — only one open at a time -->
<details class="mdst-details" name="faq" open>
<summary>Question 1</summary>
<p>Answer 1</p>
</details>
<details class="mdst-details" name="faq">
<summary>Question 2</summary>
<p>Answer 2</p>
</details>
<details class="mdst-details" name="faq">
<summary>Question 3</summary>
<p>Answer 3</p>
</details>
```
---
### Dialog `.mdst-dialog`
Modal dialog component with header, body, footer structure and multiple