8 breakpoints instead of 6: 2xs, xs, sm, md, lg, xl, 2xl, 3xl
Breakpoint prefix syntax (v1.3.0+): responsive classes use {breakpoint}:{utility}-{value} prefix format, not the Bootstrap infix format {utility}-{breakpoint}-{value}. Example: md:d-none, lg:col-6, sm:flex-row (not d-md-none, col-lg-6, flex-sm-row)
This is not Tailwind CSS. The breakpoint: prefix looks like Tailwind's responsive variants (md:flex, lg:hidden), but the resemblance stops at the colon. Utility names, values, and the delivery mechanism are still Bootstrap/OUDS, not Tailwind:
- Utility names are Bootstrap-style, not Tailwind's: d-flex/d-none (not flex/hidden), col-6 (not grid-cols-6 / w-1/2), float-end (not float-right).
- Values are OUDS semantic design tokens, not Tailwind's numeric scale: p-medium, gap-xsmall, mb-large (not p-4, gap-2, mb-8).
- There is no arbitrary-value bracket syntax (no w-[327px], bg-[#fff]) — only the fixed, pre-defined class set.
- There is no Tailwind config file, no JIT/on-demand compiler, no @apply: classes are precompiled and shipped in the theme's CSS bundle, exactly like Bootstrap.
- See Breakpoints for the full comparison.
OUDS design tokens for spacing, typography, and colors (e.g., none, 3xsmall, 2xsmall, xsmall, small, medium, large, xlarge, 2xlarge, 3xlarge)
Semantic color system with bg-surface-*, text-*, border-* token-based classes
4 color modes: light, dark, root, root-inverted (set via data-bs-theme)
Orange-specific components: header, footer, chips, tags, sticker, stepped-process, title-bar, skeleton, local-navigation, back-to-top, bullet-list, divider, quantity-selector, items (replaces Bootstrap's .list-group)
Assistant button (.btn-assistant, v1.5.0): AI-powered action button variant, distinct from standard/navigation buttons
Modified form components: switch, checkbox, radio-button, text-input, text-area, select-input, password-input use .control-item-* pattern
CSS variable prefix: --bs-
Container: use .container-fluid (not fixed .container)
Rounded corner buttons: opt-in via .use-rounded-corner-buttons on a parent container
Button variants: .btn-default, .btn-strong, .btn-brand, .btn-minimal, .btn-negative (not Bootstrap's .btn-primary, .btn-secondary, etc.)

Layout priority: grid > helpers > custom CSS

Prefer OUDS Web grid and utilities over custom CSS, <style> blocks, or inline styles for layout, flexbox, spacing, sizing, alignment, and positioning whenever an equivalent class exists. OUDS Web is a Bootstrap fork and ships both a 12-column grid and a full utility layer, so custom CSS should be the fallback described below.

Pick in this order:

Grid first — .row/.col-* (see Grid) for the page/section's overall structure: major regions, a repeating set of blocks (e.g. a list of cards), or form fields laid out in columns.
Helpers second — d-flex, .vstack/.hstack, justify-content-*, gap-*, position-*, etc. to align/space a handful of elements inside a single component (icon + label, a row of buttons, centering one element).
Custom CSS last — only if neither applies; prefer Sass variable/map overrides (see Sass) over hardcoded values.

Heuristic: structuring the page's major zones or a repeating set of blocks → grid. Aligning a few elements within one component → helpers.

Full decision table (need → class → tier) in Layout utilities. Nested grids are rare — see the note in Grid.

Quick start

OUDS Web ships as two npm packages you always need together: @ouds/web-common (shared JS/Sass) and one theme package for the brand's CSS/tokens. Pick one theme package depending on the project:

Brand	Theme package
Orange	`@ouds/web-orange`
Orange Compact	`@ouds/web-orange-compact`
Sosh	`@ouds/web-sosh`

A project must pick one theme and never mix several in the same codebase — see Themes and brands.

Recommended: install via npm (or yarn/bun):

npm install @ouds/web-common @ouds/web-orange

Then import the CSS and JS in your app, e.g.:

import '@ouds/web-orange/dist/css/ouds-web.min.css'
import * as oudsWeb from '@ouds/web-common'
// or: import { Toast, Modal } from "@ouds/web-common";

For quick prototyping without a build step, the CDN can be used instead, replacing web-orange with the theme package matching your brand:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>OUDS Web</title>
    <link
      href="https://cdn.jsdelivr.net/npm/@ouds/web-orange@<version>/dist/css/ouds-web.min.css"
      rel="stylesheet"
    />
  </head>
  <body>
    <h1>Hello, world!</h1>
    <script src="https://cdn.jsdelivr.net/npm/@ouds/web-common@<version>/dist/js/ouds-web.bundle.min.js"></script>
  </body>
</html>

Always pin <version> to a specific release (e.g. 1.4.0) rather than leaving it floating.

Reference documentation

Getting started

Installation - npm/yarn/Bun, NuGet, CDN, compiled/source download
Contents - Compiled files structure
JavaScript - Components requiring JS, plugin usage, data attributes, API
Sass - Sass customization, variables, maps, mixins
Accessibility - Accessibility guidelines
Browsers & devices - Supported browsers
Component versioning - Version tracking
Update guide - Update from previous versions
Migration from Boosted - Boosted to OUDS Web

Foundation

Approach - Design principles
Typography - Headings, body text, display, font mixins
Colors - Available raw colors
Color modes - Light/dark/root/root-inverted themes
Tokens - Raw/semantic/composite/component token architecture
CSS variables - Custom properties
Options - Sass configuration options
Reboot - CSS reset and base styles
Form validation - Validation styles
Component - Base component architecture
Themes and brands - Orange, Orange Compact, Sosh themes

Layout

Breakpoints - 8-tier responsive system
Containers - Container-fluid usage
Grid - 12-column flexbox grid
Columns - Column sizing and ordering
Gutters - Gutter spacing
CSS grid - CSS grid layout
Utilities - Layout utilities
Z-index - Z-index layers

Components

Alerts - Alert messages and inline alerts
Badges - Badge indicators
Breadcrumb - Navigation breadcrumbs
Bullet list - Styled bullet lists
Buttons - Buttons and navigation buttons
Checkbox - Checkbox controls
Chips - Filter and suggestion chips
Divider - Content dividers
Dropdown - Toggleable menus and overlays (draft component)
Footer - Page footer
Header - Responsive page header
Icon - SVG icon system
Items - Static/navigation card and list items (replaces Bootstrap's list-group)
Links - Link styles
Password input - Password field with toggle
Radio button - Radio controls
Select input - Select inputs
Skeleton - Loading placeholders
Switch - Toggle switches
Tags - Tag elements
Table - Opt-in table styling (draft component)
Text area - Multiline inputs
Text input - Single-line inputs

Not yet documented (do not invent markup)

The OUDS Web documentation site has placeholder ("Coming soon") pages for the following components — no OUDS Web-specific markup, classes, or design guidance exists for them yet: accordion, back-to-top, card, carousel, close-button, collapse, local-navigation, modal, nav-tab, navbar, offcanvas, pagination, popover, progress, quantity-selector, range, scrollspy, spinner, stepped-process, sticker, title-bar, toast, tooltip.

If a task requires one of these, tell the user it isn't documented in OUDS Web yet instead of guessing markup or falling back to plain Bootstrap classes (OUDS Web's class names, tokens, and structure regularly diverge from Bootstrap, so a Bootstrap fallback would likely be wrong).

Utilities

Figma tokens mapping - Mapping Figma design tokens to utility classes/variables
Aspect ratio - Aspect ratio containers
Background - Background utilities
Border - Border utilities
Color - Text color utilities
Display - Display property
Flex - Flexbox utilities
Float - Float positioning
Interaction - User interaction
Object fit - Object-fit utilities
Opacity - Opacity levels
Overflow - Overflow behavior
Position - Positioning
Shadow - Box shadows
Sizing - Width and height
Spacing - Margin, padding, gap
Stack - Vertical/horizontal stacks
Stretched link - Stretched clickable areas
Text - Text alignment, wrapping, transform
Text truncation - Text overflow
Vertical align - Vertical alignment
Visibility - Visibility toggling
Visually hidden - Screen reader only
Z-index - Z-index utilities

Quick search

grep -ri "btn-" references/components/buttons.md
grep -ri "breakpoint" references/layout/breakpoints.md
grep -ri "data-bs-theme" references/foundation/color-modes.md
grep -ri "control-item" references/components/
grep -ri "\.bg-" references/utilities/background.md
grep -ri "spacing\|margin\|padding" references/utilities/spacing.md
grep -ri "d-flex\|justify-content\|align-items\|flex-" references/utilities/flex.md
grep -ri "vstack\|hstack" references/utilities/stack.md
grep -ri "\.col-\|row-cols" references/layout/grid.md
grep -ri "sticky\|fixed-\|translate-middle" references/utilities/position.md

Critical conventions

Spacing tokens

Use OUDS token names instead of Bootstrap numeric values:

Class pattern	Example	Meaning
`{p\|m}{t\|b\|s\|e\|x\|y}-{token}`	`p-medium`	padding medium
`gap-{token}`	`gap-xsmall`	flex/grid gap
Tokens	`none`, `3xsmall`, `2xsmall`, `xsmall`, `small`, `medium`, `large`, `xlarge`, `2xlarge`-`5xlarge`

Color modes

<div data-bs-theme="light">Always light</div>
<div data-bs-theme="dark">Always dark</div>
<div data-bs-theme="root">Follows page theme</div>
<div data-bs-theme="root-inverted">Opposite of page theme</div>

Form components pattern

OUDS Web form components use .control-item-* classes:

<ul class="control-items-list">
  <li class="switch-item">
    <div class="control-item-assets-container">
      <input
        class="control-item-indicator"
        type="checkbox"
        role="switch"
        id="mySwitch"
      />
    </div>
    <div class="control-item-text-container">
      <label class="control-item-label" for="mySwitch">Label</label>
    </div>
  </li>
</ul>

Button variants

<button class="btn btn-default">Default</button>
<button class="btn btn-strong">Strong</button>
<button class="btn btn-brand">Brand</button>
<button class="btn btn-minimal">Minimal</button>
<button class="btn btn-negative">Negative</button>
<!-- Navigation buttons -->
<a class="btn btn-next btn-default" href="#">Next</a>
<!-- Assistant button (AI-powered actions, v1.5.0) -->
<button class="btn btn-assistant">Assistant</button>
<!-- On colored backgrounds, add btn-on-colored-bg -->
<button class="btn btn-default btn-on-colored-bg">On colored bg</button>

Icons (SVG sprite)

<svg width="1.5rem" height="1.5rem" fill="currentColor" aria-hidden="true">
  <use xlink:href="path/to/ouds-web-sprite.svg#icon-name"></use>
</svg>

Reminder

Layout, flexbox, spacing, sizing, and positioning almost always have a matching OUDS Web class. Grid (.row/.col-*) for page/section structure, then helpers (d-flex, .vstack/.hstack, gap-*, etc.) for alignment inside a component — see Layout priority. Reach for a class before writing a Sass rule, a <style> block, or an inline style="..." attribute.

using-ouds-web-version-major-minor

OUDS Web Library Reference

Overview