orange-opensource/orange-boosted-bootstrap/using-ouds-web-version-major-minor

OUDS Web Library Reference

Overview

OUDS Web is Orange's web implementation of the Orange Unified Design System. It is a fork of Bootstrap with significant modifications for Orange branding and accessibility.

Key differences from standard Bootstrap:

• 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:

1. 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.
2. 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).
3. 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:

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