From 84824718fcb703edc02ab53bf57deabf92727aac Mon Sep 17 00:00:00 2001 From: Vincent Prothais Date: Tue, 31 Mar 2026 10:01:30 +0200 Subject: [PATCH 01/17] First generated version of agents.md --- .ai/ACCESSIBILITY.md | 17 ++ .ai/ARCHITECTURE.md | 16 ++ .ai/CODE_CONVENTIONS.md | 14 + .ai/COMPONENTS.md | 15 + .ai/DESIGN_TOKENS.md | 16 ++ AGENTS.md | 588 ++++++++++++++++++++++++++++++++++++++++ 6 files changed, 666 insertions(+) create mode 100644 .ai/ACCESSIBILITY.md create mode 100644 .ai/ARCHITECTURE.md create mode 100644 .ai/CODE_CONVENTIONS.md create mode 100644 .ai/COMPONENTS.md create mode 100644 .ai/DESIGN_TOKENS.md create mode 100644 AGENTS.md diff --git a/.ai/ACCESSIBILITY.md b/.ai/ACCESSIBILITY.md new file mode 100644 index 0000000000..f0f77025ae --- /dev/null +++ b/.ai/ACCESSIBILITY.md @@ -0,0 +1,17 @@ +# Accessibility β€” OUDS Web + +> WCAG 2.1 AA compliance guide for OUDS Web components. +> For a quick overview, see the [Accessibility section in AGENTS.md](../AGENTS.md#accessibility-requirements). + +πŸ”œ **This file is planned.** It will cover: + +- WCAG 2.1 Level AA checklist per component type +- ARIA patterns reference (dialogs, tabs, accordions, dropdowns, etc.) +- Keyboard navigation requirements per component +- Focus management patterns (focus trapping, focus restoration) +- Color contrast requirements and testing tools +- Pa11y-CI configuration and custom rules +- Screen reader testing strategy +- Touch target sizing guidelines +- Motion and animation accessibility +- RTL layout testing diff --git a/.ai/ARCHITECTURE.md b/.ai/ARCHITECTURE.md new file mode 100644 index 0000000000..22dd28768a --- /dev/null +++ b/.ai/ARCHITECTURE.md @@ -0,0 +1,16 @@ +# Architecture β€” OUDS Web + +> Detailed architecture reference for the OUDS Web monorepo. +> For a quick overview, see the [Architecture section in AGENTS.md](../AGENTS.md#architecture-overview). + +πŸ”œ **This file is planned.** It will cover: + +- Build pipeline details (Rollup, PostCSS, Sass, terser) +- Package publishing workflow (npm workspaces) +- CI/CD pipeline and GitHub Actions +- Astro documentation site structure +- Brand-parameterized routing in the docs site +- Storybook auto-generation from docs +- SRI hash generation for CDN assets +- Version management across packages +- RTL CSS generation via rtlcss diff --git a/.ai/CODE_CONVENTIONS.md b/.ai/CODE_CONVENTIONS.md new file mode 100644 index 0000000000..fe8913d0a1 --- /dev/null +++ b/.ai/CODE_CONVENTIONS.md @@ -0,0 +1,14 @@ +# Code Conventions β€” OUDS Web + +> Detailed style guide for HTML, SCSS, and JavaScript contributions to OUDS Web. +> For a quick overview, see the [Code conventions section in AGENTS.md](../AGENTS.md#code-conventions). + +πŸ”œ **This file is planned.** It will cover: + +- Full HTML style guide (attribute order, semantic elements, ARIA patterns) +- SCSS naming conventions (`$component-state-property-size`) +- SCSS linter rules (Stylelint config details) +- JavaScript style guide (ESLint config details) +- Comment conventions (`// OUDS mod:` prefix, `scss-docs-start/end` markers) +- File organization and naming patterns +- EditorConfig and formatting rules diff --git a/.ai/COMPONENTS.md b/.ai/COMPONENTS.md new file mode 100644 index 0000000000..52b85f5e3c --- /dev/null +++ b/.ai/COMPONENTS.md @@ -0,0 +1,15 @@ +# Components β€” OUDS Web + +> Full component catalog and development guide for OUDS Web. +> For a quick overview, see the [Components section in AGENTS.md](../AGENTS.md#components-catalog). + +πŸ”œ **This file is planned.** It will cover: + +- Full component catalog with SCSS, JS, and token file locations +- Component creation guide (step-by-step) +- SCSS component patterns and conventions +- JavaScript component patterns (BaseComponent API) +- Testing patterns (Karma + Jasmine unit tests) +- Documentation patterns (MDX content for Astro site) +- Storybook story patterns +- Component token definition guide diff --git a/.ai/DESIGN_TOKENS.md b/.ai/DESIGN_TOKENS.md new file mode 100644 index 0000000000..f73fd612bc --- /dev/null +++ b/.ai/DESIGN_TOKENS.md @@ -0,0 +1,16 @@ +# Design Tokens β€” OUDS Web + +> Full reference for the token system powering OUDS Web's multi-brand architecture. +> For a quick overview, see the [Design tokens section in AGENTS.md](../AGENTS.md#design-tokens-system). + +πŸ”œ **This file is planned.** It will cover: + +- Complete token layer reference (raw, semantic, composite, component) +- Token naming scheme with full examples +- How to add new tokens to a brand +- How to add new tokens to all brands +- Base multiplier system details +- CSS custom properties and color-mode switching +- Token version management (OUDS Core, brand-specific versions) +- How `_variables.scss` maps Bootstrap variables to OUDS tokens +- Brand override guide: customizing tokens for a new brand diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..c01ad712e7 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,588 @@ +# OUDS Web β€” AI Agent Context + +> **OUDS Web** is a multi-brand design system for the web, built as a fork of Bootstrap 5.3.6. +> It ships accessible, token-driven UI components for Orange group brands (Orange, Sosh, Orange Compact). + +| Key info | Value | +|---|---| +| Version | 1.1.0 | +| Upstream | Bootstrap 5.3.6 | +| Main branch | `ouds/main` | +| License | MIT (code) / CC BY 3.0 (docs) | +| Docs | | +| Repo | | + +--- + +## Table of contents + +1. [Architecture overview](#architecture-overview) +2. [Monorepo structure](#monorepo-structure) +3. [Design tokens system](#design-tokens-system) +4. [Multi-brand system](#multi-brand-system) +5. [Components catalog](#components-catalog) +6. [Code conventions](#code-conventions) +7. [Accessibility requirements](#accessibility-requirements) +8. [Quick-start examples](#quick-start-examples) +9. [Anti-patterns](#anti-patterns) +10. [AI agent workflow](#ai-agent-workflow) +11. [Extended documentation](#extended-documentation) + +--- + +## Architecture overview + +OUDS Web is a **monorepo** with npm workspaces. It publishes: + +- **`@ouds/web-common`** β€” Shared SCSS source files, JavaScript components (compiled to `dist/js/`). This is the root package. +- **`@ouds/web-orange`** β€” Orange brand tokens + compiled CSS (`dist/css/`). +- **`@ouds/web-sosh`** β€” Sosh brand tokens + compiled CSS. +- **`@ouds/web-orange-compact`** β€” Orange Compact brand tokens + compiled CSS. + +**Key principle**: JavaScript is shared across all brands. Only CSS/tokens differ per brand. + +``` +Consumer installs: @ouds/web-common (JS) + @ouds/web- (CSS) +``` + +### Tech stack + +| Layer | Technology | +|---|---| +| Markup | Semantic HTML5 | +| Styles | SCSS β†’ CSS (via `sass` 1.78) + PostCSS (autoprefixer, RTL via rtlcss) | +| Scripts | Vanilla JavaScript (ES modules), bundled with Rollup | +| Tokens | SCSS variables + CSS custom properties | +| Docs site | Astro 5.x with MDX content collections | +| Testing | Karma + Jasmine (JS), Pa11y-CI (a11y), VNU (HTML validation), Stylelint, ESLint | +| Storybook | `@storybook/html-vite` with a11y addon | + +--- + +## Monorepo structure + +``` +Orange-Boosted-Bootstrap/ +β”œβ”€β”€ package.json # Root: @ouds/web-common β€” shared JS + SCSS source +β”œβ”€β”€ scss/ # πŸ”΅ Common SCSS (components, mixins, utilities, variables) +β”‚ β”œβ”€β”€ _variables.scss # Bootstrap variables mapped to OUDS tokens +β”‚ β”œβ”€β”€ _variables-dark.scss # Dark mode variable overrides +β”‚ β”œβ”€β”€ _config.scss # $prefix: bs-, $color-mode-type, $ouds-root-selector +β”‚ β”œβ”€β”€ _functions.scss # Sass functions +β”‚ β”œβ”€β”€ _maps.scss # Sass maps +β”‚ β”œβ”€β”€ _mixins.scss # Mixin index +β”‚ β”œβ”€β”€ mixins/ # 28 mixin files (breakpoints, buttons, focus, grid…) +β”‚ β”œβ”€β”€ forms/ # 11 form component partials +β”‚ β”œβ”€β”€ helpers/ # 9 helper classes (visually-hidden, focus-ring, stacks…) +β”‚ β”œβ”€β”€ utilities/ # _api.scss β€” utility class generator +β”‚ β”œβ”€β”€ _accordion.scss # Component partials (one file per component) +β”‚ β”œβ”€β”€ _buttons.scss +β”‚ β”œβ”€β”€ _modal.scss +β”‚ └── … # ~40 component SCSS partials +β”œβ”€β”€ js/ +β”‚ β”œβ”€β”€ src/ # πŸ”΅ JavaScript source (ES modules) +β”‚ β”‚ β”œβ”€β”€ base-component.js # Abstract base class for all components +β”‚ β”‚ β”œβ”€β”€ alert.js # 15 component modules +β”‚ β”‚ β”œβ”€β”€ dom/ # 4 DOM helpers (event-handler, data, manipulator, selector-engine) +β”‚ β”‚ └── util/ # 9 utility modules (focustrap, backdrop, swipe, sanitizer…) +β”‚ β”œβ”€β”€ dist/ # Compiled individual plugins +β”‚ └── tests/ # Unit and integration tests +β”œβ”€β”€ dist/ # πŸ”΅ Compiled common JS output +β”‚ └── js/ # ouds-web.js, .esm.js, .bundle.js (+ minified + sourcemaps) +β”œβ”€β”€ packages/ +β”‚ β”œβ”€β”€ orange/ # 🟠 Orange brand package (@ouds/web-orange) +β”‚ β”‚ β”œβ”€β”€ package.json +β”‚ β”‚ β”œβ”€β”€ config.yml # Brand-specific site config (name, CDN URLs, Algolia…) +β”‚ β”‚ β”œβ”€β”€ scss/ +β”‚ β”‚ β”‚ β”œβ”€β”€ ouds-web.scss # Main entry: imports common + Orange tokens +β”‚ β”‚ β”‚ └── tokens/ # _raw.scss, _semantic.scss, _composite.scss, _component.scss +β”‚ β”‚ β”‚ # + _semantic-colors-custom-props.scss +β”‚ β”‚ β”‚ # + _component-colors-custom-props.scss +β”‚ β”‚ └── dist/css/ # Compiled brand CSS (LTR, RTL, minified) +β”‚ β”œβ”€β”€ sosh/ # 🟣 Sosh brand package (@ouds/web-sosh) +β”‚ β”‚ └── (same structure as orange) +β”‚ └── orange-compact/ # 🟠 Orange Compact brand package +β”‚ └── (same structure as orange) +β”œβ”€β”€ site/ # πŸ“– Astro documentation site +β”‚ β”œβ”€β”€ src/ +β”‚ β”‚ β”œβ”€β”€ content/docs/ # MDX doc pages organized by section +β”‚ β”‚ β”œβ”€β”€ components/ # Astro components (shortcodes, partials, layouts) +β”‚ β”‚ β”œβ”€β”€ layouts/ # BaseLayout, DocsLayout, ExamplesLayout… +β”‚ β”‚ β”œβ”€β”€ libs/ # 18 TypeScript utility modules +β”‚ β”‚ └── pages/ # Brand-parameterized routes: /[brand]/docs/… +β”‚ └── data/ # Shared data files +β”œβ”€β”€ stories/ # πŸ“˜ Storybook stories (auto-generated from docs) +β”œβ”€β”€ build/ # πŸ”§ Build scripts (Rollup, PostCSS, SRI, version, VNU…) +β”œβ”€β”€ fonts/ # Custom font files +└── .storybook/ # Storybook configuration +``` + +### Important files to know + +| File | Purpose | +|---|---| +| `scss/_config.scss` | CSS prefix (`bs-`), color-mode type, root selector | +| `scss/_variables.scss` | All Bootstrap variables remapped to OUDS tokens (~2200 lines) | +| `packages//scss/tokens/_index.scss` | Token import order for each brand | +| `packages//scss/ouds-web.scss` | Brand entry point β€” imports common + tokens | +| `packages//config.yml` | Brand metadata (name, CDN URLs, docs config) | +| `build/rollup.config.mjs` | JS build configuration | +| `build/postcss.config.mjs` | CSS post-processing (autoprefixer) | + +--- + +## Design tokens system + +Tokens are the single source of truth for all visual properties. They follow a **3-tier hierarchy**: + +### Token layers + +``` +Raw (primitives) β†’ Semantic β†’ Component +$core-ouds-* $ouds-* $ouds--* +``` + +| Layer | Prefix | Location | Purpose | +|---|---|---|---| +| **Raw** | `$core-ouds-*`, `$core-orange-*` | `tokens/_raw.scss` | Primitive values (colors, dimensions, base units). **Never use directly in component SCSS.** | +| **Semantic** | `$ouds-*` | `tokens/_semantic.scss` | Meaningful aliases (e.g., `$ouds-border-radius-default`). Maps raw tokens to design intent. | +| **Composite** | `$ouds-*` | `tokens/_composite.scss` | Combined values (elevation, font stacks, font-face). | +| **Component** | `$ouds--*` | `tokens/_component.scss` | Per-component tokens (e.g., `$ouds-button-border-radius-default`). References semantic tokens. | +| **CSS Custom Props** | `--bs-*` | `tokens/_*-custom-props.scss` | Runtime tokens exposed as CSS custom properties for color-mode switching. | + +### Token naming convention + +```scss +// Raw: $core-ouds-{category}-{value} +$core-ouds-border-radius-100: 4px; + +// Semantic: $ouds-{category}-{variant} +$ouds-border-radius-default: $core-ouds-border-radius-0; + +// Component: $ouds-{component}-{category}-{variant} +$ouds-button-border-radius-default: $ouds-border-radius-default; +``` + +### Base multiplier system + +Raw tokens use a base-multiplier pattern for consistency: + +```scss +$core-ouds-border-base: 4px !default; +$core-ouds-border-radius-100: $core-ouds-border-base * 1; // 4px +$core-ouds-border-radius-200: $core-ouds-border-base * 2; // 8px +$core-ouds-border-radius-300: $core-ouds-border-base * 3; // 12px +``` + +### CSS custom properties and color modes + +Color tokens are exposed as CSS custom properties to support light/dark mode at runtime: + +```scss +// In tokens/_semantic-colors-custom-props.scss +@include color-mode(light, true) { + --#{$prefix}color-action-enabled: #{$ouds-color-action-enabled-light}; + --#{$prefix}color-bg-primary: #{$ouds-color-bg-primary-light}; +} + +@include color-mode(dark) { + --#{$prefix}color-action-enabled: #{$ouds-color-action-enabled-dark}; + --#{$prefix}color-bg-primary: #{$ouds-color-bg-primary-dark}; +} +``` + +All variables use `!default` to allow consumer overrides. + +--- + +## Multi-brand system + +Each brand package follows the **same structure** but provides different token values. + +### How brand theming works + +1. **Shared core**: `$core-ouds-*` tokens are identical across brands (OUDS Core v1.9.0). +2. **Brand-specific**: `$core-orange-*` / `$core-sosh-*` tokens differ per brand (colors, fonts, etc.). +3. **Semantic mapping**: Each brand maps raw tokens to semantic tokens differently. +4. **Component tokens**: Reference semantic tokens β€” automatically adapted per brand. + +### Brand entry point pattern + +Every brand's `ouds-web.scss` follows the same structure: + +```scss +// packages//scss/ouds-web.scss +@import "@ouds/web-common/scss/config"; +@import "@ouds/web-common/scss/functions"; +@import "@ouds/web-/scss/tokens"; // ← Brand tokens injected here +@import "@ouds/web-common/scss/variables"; +@import "@ouds/web-common/scss/variables-dark"; +@import "@ouds/web-common/scss/maps"; +@import "@ouds/web-common/scss/mixins"; +@import "@ouds/web-common/scss/utilities"; + +// Then all common layout & component imports… +@import "@ouds/web-common/scss/root"; +@import "@ouds/web-common/scss/reboot"; +// … +``` + +### Token import order (within each brand) + +```scss +// packages//scss/tokens/_index.scss +@import "raw"; // 1. Primitive values +@import "semantic"; // 2. Semantic mappings +@import "semantic-colors-custom-props"; // 3. CSS custom properties (semantic) +@import "composite"; // 4. Composite tokens (elevation, fonts) +@import "component-colors-custom-props"; // 5. CSS custom properties (component) +@import "component"; // 6. Component-level tokens +``` + +### Adding or modifying tokens for a brand + +- Edit files in `packages//scss/tokens/`. +- Raw tokens: `_raw.scss` β€” brand primitives. +- Semantic tokens: `_semantic.scss` β€” how primitives map to design intent. +- Component tokens: `_component.scss` β€” per-component overrides. +- Color custom props: `_*-custom-props.scss` β€” light/dark mode values. + +--- + +## Components catalog + +### OUDS-specific components (beyond Bootstrap) + +| Component | SCSS | JS | Description | +|---|---|---|---| +| Back to top | `_back-to-top.scss` | β€” | Scroll-to-top button | +| Bullet list | `_bullet-list.scss` | β€” | Styled unordered lists | +| Chips | `_chips.scss` | β€” | Compact interactive elements | +| Footer | `_footer.scss` | β€” | Structured page footer | +| Local navigation | `_local-navigation.scss` | β€” | In-page anchor navigation | +| Orange navbar | `_orange-navbar.scss` | `orange-navbar.js` | Brand-specific navigation bar | +| Quantity selector | `forms/_quantity-selector.scss` | `quantity-selector.js` | Numeric stepper input | +| Skeleton | `_skeleton.scss` | β€” | Loading placeholder | +| Star rating | `forms/_star-rating.scss` | β€” | Rating input (CSS-only) | +| Stepped process | `_stepped-process.scss` | β€” | Multi-step progress indicator | +| Sticker | `_sticker.scss` | β€” | Promotional badge/label | +| Tags | `_tags.scss` | β€” | Labeling/categorization elements | +| Title bars | `_title-bars.scss` | β€” | Section header bars | + +### Bootstrap components (customized) + +Accordion, Alert, Badge, Breadcrumb, Button, Button group, Card, Carousel, Collapse, Dropdown, Forms (control, select, range, validation, labels, input-group), Grid, Images, Links, List group, Modal, Nav/Tab, Navbar, Offcanvas, Pagination, Popover, Progress, Scrollspy, Spinner, Table, Toast, Tooltip, Typography. + +### JavaScript components + +All JS components extend `BaseComponent` (`js/src/base-component.js`) and follow a consistent API: + +```javascript +// Pattern for all JS components +import BaseComponent from './base-component.js' + +class MyComponent extends BaseComponent { + static get NAME() { return 'myComponent' } + // ... +} +``` + +Available JS components: Alert, Button, Carousel, Collapse, Dropdown, Modal, Offcanvas, OrangeNavbar, Popover, QuantitySelector, Scrollspy, Tab, Toast, Tooltip. + +### Finding component code + +| What you need | Where to look | +|---|---| +| Component SCSS | `scss/_.scss` or `scss/forms/_.scss` | +| Component JS | `js/src/.js` | +| Component tokens | `packages//scss/tokens/_component.scss` (search for `ouds--*`) | +| Component docs | `site/src/content/docs/components/.mdx` | +| Component tests | `js/tests/unit/.spec.js` | + +--- + +## Code conventions + +### HTML + +- **Semantic elements**: Use `