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