update instructions for copilot

Author: vprothais

.github/copilot-instructions.md

@@ -2,76 +2,57 @@
 applyTo: "**"
 ---
 
-# OUDS Web — AI Agent Instructions
+# OUDS Web — Project Context
 
-You are working in **OUDS Web** (Orange Unified Design System — Web), a multi-brand design system built as a fork of Bootstrap 5.3.6.
-Version: 1.1.0 | Main branch: `ouds/main` | Brands: Orange, Sosh, Orange Compact
+**OUDS Web** (Orange Unified Design System — Web) is a multi-brand design system built as a fork of Bootstrap 5.3.6. It serves 3 brands (Orange, Sosh, Orange Compact) from a single codebase where only CSS tokens differ per brand — JavaScript is fully shared.
 
----
-
-## Standards — Apply Always
-
-The following standards define mandatory conventions. Always apply them when writing or reviewing code:
-
-- **[Code Conventions](.packmind/standards/ouds-code-conventions.md)** — HTML/SCSS/JS style rules: `!default` on variables, forbidden direct properties (`border-radius`, `transition`), forbidden values (`border: none`, `lighten()`), token usage, JS no-semicolons, template literals.
-
-- **[Accessibility WCAG 2.2 AAA (with AA fallback)](.packmind/standards/ouds-accessibility-wcag.md)** — Target WCAG 2.2 Level AAA with documented fallback to AA for specific color and UI constraints. Non-negotiable: `@include focus-visible()`, ARIA attributes, `.visually-hidden`, keyboard navigation, 7:1 text contrast (AAA) / 4.5:1 fallback (AA), 44×44px touch targets, RTL support, cognitive accessibility.
-
-- **[Design Token System](.packmind/standards/ouds-design-tokens.md)** — 3-tier hierarchy (raw → semantic → component). Never edit auto-generated files (`_raw.scss`, `_semantic.scss`, `_component.scss`, `_*-custom-props.scss`). Colors via `var(--#{$prefix}color-*)`. New tokens in all 3 brands.
-
-- **[Component Patterns](.packmind/standards/ouds-component-patterns.md)** — CSS custom property declaration at top of class, state overrides via variable overrides, `scss-docs-start/end` markers, `// OUDS mod:` comments, JS BaseComponent pattern.
-
----
-
-## Commands — Use for Specific Workflows
-
-When the user asks to perform a specific task, load and follow the appropriate command:
-
-- **[ouds-create-component](.packmind/commands/ouds-create-component.md)** — Full step-by-step guide for creating a new SCSS/JS component (SCSS structure, tokens per brand, ARIA, JS boilerplate, tests, docs).
+## Quick Reference
 
-- **[ouds-diagnose-error](.packmind/commands/ouds-diagnose-error.md)** — Diagnostic workflow for Stylelint, ESLint, Sass build, CI, token, JS test, and Pa11y errors.
-
-- **[ouds-decision-routing](.packmind/commands/ouds-decision-routing.md)** — 4 decision trees (where to put code, which token, multi-brand updates, testing strategy).
-
-- **[ouds-lookup](.packmind/commands/ouds-lookup.md)** — Quick lookup index: maps any topic to the right standard, command, or skill.
-
-- **[ouds-validate-tokens](.packmind/commands/ouds-validate-tokens.md)** — Read-only audit: cross-brand token presence check and anti-pattern detection for SCSS component files.
+| Key | Value |
+|---|---|
+| Version | 1.1.0 |
+| Main branch | `ouds/main` |
+| CSS prefix | `--bs-` (via `$prefix`) |
+| Build | `npm run dist` |
+| Lint | `npm run lint` |
+| Tests | `npm run test` |
+| Dev servers | `:9001` (orange) · `:9002` (sosh) · `:9003` (orange-compact) |
 
----
+## Critical Constraints
 
-## Skills — Domain Knowledge
+These rules are non-negotiable and apply to every contribution:
 
-Load these skills when deep conceptual understanding is needed:
+1. **Use tokens, not hardcoded values** — colors, spacing, dimensions all come from the OUDS token system.
+2. **Use mixins for `border-radius` and `transition`** — direct CSS properties are forbidden by Stylelint.
+3. **Auto-generated token files are read-only** — never edit `_raw.scss`, `_semantic.scss`, `_component.scss`, or `_*-custom-props.scss`. Only `_composite.scss` is hand-editable.
+4. **Never commit `dist/`** — build artifacts are generated in CI.
+5. **JavaScript lives in `js/src/` only** — never in `packages/<brand>/`.
+6. **Colors use CSS custom properties** — `var(--#{$prefix}color-*)` enables runtime dark mode switching.
+7. **Accessibility is mandatory** — visible `:focus-visible`, ARIA attributes on all interactive elements, `.visually-hidden` for SR content.
 
-- **[ouds-token-strategy](.packmind/skills/ouds-token-strategy.md)** — Full token architecture: pipeline, layer hierarchy, CSS custom property bridge for dark mode, color token dual-track, consumption patterns. Load when asked about tokens, dark mode, or brand differentiation.
+## Scoped Instructions
 
-- **[ouds-multi-brand-sync](.packmind/skills/ouds-multi-brand-sync.md)** — 3-brand architecture: what is shared, what differs, when to update all brands, brand entry point pattern, testing multi-brand changes.
+Detailed conventions are loaded automatically based on the files you're working on. They live in `.github/instructions/`:
 
-- **[ouds-knowledge-base](.packmind/skills/ouds-knowledge-base.md)** — Full glossary (154 terms), build pipeline, npm scripts reference, CI/CD jobs, release process, and project file map. Load when encountering unfamiliar terms or working on build/infra.
+- `scss.instructions.md` — SCSS conventions and patterns
+- `javascript.instructions.md` — JS conventions
+- `html-accessibility.instructions.md` — HTML structure and WCAG compliance
+- `tokens.instructions.md` — Token system rules
+- `components.instructions.md` — Component SCSS/JS patterns
+- `multi-brand.instructions.md` — Cross-brand synchronization
 
----
+## Workflows
 
-## Critical Constraints (Always Active)
+For complex multi-step tasks, follow the dedicated workflow guides:
 
-1. **Never hardcode** colors (`#ff7900`), spacing (`16px`), or dimensions — use OUDS tokens.
-2. **Never use `border-radius: X` or `transition: X` directly** — use `@include border-radius()` / `@include transition()`.
-3. **Never edit auto-generated token files**: `_raw.scss`, `_semantic.scss`, `_component.scss`, `_*-custom-props.scss` — only `_composite.scss` is editable.
-4. **Never commit `dist/`** files — they are build artifacts.
-5. **Never put JavaScript** in `packages/<brand>/` — JS is shared via `js/src/`.
-6. **Color tokens for dark mode** → always `var(--#{$prefix}color-*)`, never the SCSS variable directly.
-7. **Accessibility**: never remove `:focus-visible` styles, always add ARIA attributes to interactive components, never use `display: none` for screen-reader content.
+- `workflows/create-component.instructions.md` — Creating a new component
+- `workflows/diagnose-errors.instructions.md` — Debugging build/lint/CI errors
+- `workflows/validate-tokens.instructions.md` — Auditing token usage
 
----
+## Deep References
 
-## Project Quick Facts
+For in-depth architecture knowledge, read the reference docs in `.github/instructions/references/`:
 
-| | |
-|---|---|
-| CSS prefix | `--bs-` (via `$prefix` in `scss/_config.scss`) |
-| Brands | orange, sosh, orange-compact |
-| JS components | 15 (all extend `BaseComponent`) |
-| Token layers | raw → semantic → composite → component → CSS custom props |
-| Build | `npm run dist` (CSS + JS) |
-| Lint | `npm run lint` |
-| Tests | `npm run test` |
-| Dev servers | `:9001` (orange), `:9002` (sosh), `:9003` (orange-compact) |
+- `token-architecture.md` — Full token pipeline and layer hierarchy
+- `glossary.md` — 154 project-specific terms
+- `project-map.md` — File structure, npm scripts, CI/CD jobs

.github/instructions/components.instructions.md

@@ -0,0 +1,155 @@
+---
+name: component-patterns
+description: >
+  SCSS and JavaScript structural patterns for OUDS Web components. Covers CSS custom
+  property declarations, state management via variable overrides, documentation markers,
+  icon patterns, and responsive overrides. Applied when working on component files.
+applyTo: "scss/_*.scss,scss/forms/_*.scss,js/src/*.js"
+---
+
+# Component Patterns
+
+## Core principle
+
+Every component declares CSS custom properties at the top, then consumes them via `var()`. State changes override the *variable*, not the *property*. This creates a single point of truth and enables runtime theming.
+
+---
+
+## SCSS component structure
+
+```scss
+// scss/_my-component.scss
+
+// Root-level shared variables (if needed by child components)
+#{$ouds-root-selector} {
+  --#{$prefix}my-component-border-radius: #{$ouds-border-radius-default};
+}
+
+.my-component {
+  // scss-docs-start my-component-css-vars
+  --#{$prefix}my-component-padding: #{$ouds-my-component-space-padding-block};
+  --#{$prefix}my-component-color: #{$ouds-color-content-default};
+  --#{$prefix}my-component-bg: #{$ouds-color-bg-primary};
+  // scss-docs-end my-component-css-vars
+
+  padding: var(--#{$prefix}my-component-padding);
+  color: var(--#{$prefix}my-component-color);
+  background-color: var(--#{$prefix}my-component-bg);
+  @include border-radius(var(--#{$prefix}my-component-border-radius));
+  @include transition($transition-base);
+
+  &:hover {
+    --#{$prefix}my-component-bg: #{$ouds-color-bg-secondary};
+  }
+
+  &:focus-visible {
+    @include focus-visible();
+  }
+
+  &:disabled,
+  &[aria-disabled="true"] {
+    --#{$prefix}my-component-color: #{$ouds-color-content-disabled};
+    pointer-events: none;
+  }
+}
+
+// Variants override variables, not properties
+.my-component-variant {
+  --#{$prefix}my-component-bg: #{$ouds-color-surface-brand};
+}
+```
+
+---
+
+## Key patterns
+
+### State overrides via custom properties
+
+Override the CSS custom property in pseudo-classes/variants — the `var()` references update automatically. This avoids duplicating property declarations.
+
+```scss
+// ✓ override the variable
+&:hover {
+  --#{$prefix}chip-bg: #{$ouds-chip-color-bg-unselected-hover};
+}
+
+// ✗ re-declaring the property — harder to maintain
+&:hover {
+  background-color: $ouds-chip-color-bg-unselected-hover;
+}
+```
+
+### Documentation markers
+
+The Astro docs site extracts CSS custom property tables using these markers. Every component's variable block needs them:
+
+```scss
+// scss-docs-start badge-css-vars
+--#{$prefix}badge-size: #{$value};
+// scss-docs-end badge-css-vars
+```
+
+### Border-width compensation
+
+Prevent layout shifts when borders change on interaction (e.g., hover adds a thicker border):
+
+```scss
+padding: calc(var(--#{$prefix}btn-padding-y) - var(--#{$prefix}btn-border-width))
+         calc(var(--#{$prefix}btn-padding-x) - var(--#{$prefix}btn-border-width));
+```
+
+### Icon pattern (`mask-image`)
+
+Icons use mask-image to inherit color from `currentcolor`:
+
+```scss
+&::before {
+  content: "";
+  display: inline-block;
+  background-color: currentcolor;
+  mask-image: escape-svg(var(--#{$prefix}some-icon));
+  mask-size: 100%;
+  mask-repeat: no-repeat;
+}
+```
+
+### Responsive overrides
+
+Override the custom property at the breakpoint — don't duplicate rulesets:
+
+```scss
+// ✓
+.component {
+  --#{$prefix}component-width: #{$mobile-width};
+
+  @include media-breakpoint-up(xl) {
+    --#{$prefix}component-width: #{$desktop-width};
+  }
+}
+```
+
+---
+
+## Bootstrap override markers
+
+Every deviation from Bootstrap upstream must be marked for merge visibility:
+
+```scss
+display: flex; // OUDS mod: instead of `inline-block`
+// OUDS mod: no `@include rfs($btn-font-size, ...)`
+
+// OUDS mod: loading buttons
+.btn.loading-indeterminate { ... }
+// End mod
+```
+
+---
+
+## JavaScript component pattern
+
+See `javascript.instructions.md` for the full BaseComponent structure. Key reminders:
+
+- Extend `BaseComponent`, expose static `NAME` getter
+- Use `data-bs-*` attributes for configuration — never inline handlers
+- JS lives in `js/src/` only — never in `packages/<brand>/`
+- Register in `js/index.esm.js` and `js/index.umd.js`