@klodd/ds 3.14.13 → 3.15.0

package/references/04-locked-decisions/0011-strikt-bem-elementsyntax.md

@@ -0,0 +1,133 @@
+# 0011 - Strikt BEM-elementsyntax för inre struktur av compound-blocks
+
+## Status
+Locked.
+
+## Context
+
+Regel 11 i `03-quality-bar.md` (compound blocks i samma fil) öppnade
+för flat-hyphen-klasser via sibling-relation-undantaget. Den nuvarande
+formuleringen säger:
+
+> Ett block som logiskt kunde varit BEM-element av ett annat - i så
+> fall ska det vara `.X__Y`, inte `.X-Y` som separat block.
+
+Detta var stipulerat men inte konsekvent verkställt i app-domain-CSS.
+Jubbs `jubb.css` och `pages/triage.css` ackumulerade ~28 flat-hyphen-
+klasser som logiskt var inre struktur av compound-blocks men namngivna
+utan `__`-syntax (`.score-dim-row` istället för `.score-breakdown__dim-row`,
+`.triage-source` istället för `.triage-card__source` etc).
+
+Ekonoms domain-CSS (`ekonom.css`) har också compound-block-undantag
+men dessa är dokumenterade som Sprint G Tier D-undantag (2026-05-09)
+med specifik rationale (visuell paritet, etablerade namn, lyft-värda
+till paketet).
+
+Skärpning behövdes för att:
+1. Förtydliga vad "kunde varit BEM-element" betyder (test-baserat)
+2. Stänga gapet där LLM-sessioner skapade flat-hyphen-inner-element
+   med felklassificering som "sibling"
+3. Etablera dokumenterad Tier D-katalog som hindrar nya odokumenterade
+   undantag
+
+## Decision
+
+Compound-blocks i samma fil är OK ENDAST när alla följande gäller:
+
+1. **JSDoc-header med `Blocks:`-sektion** (oförändrat krav från regel 11)
+2. **Listade i `02-components.md`** (oförändrat krav)
+3. **Inre struktur av compound-block MÅSTE använda BEM-element-syntax
+   (`__element`).** Bara root-level sibling-blocks (genuint fristående
+   koncept) får vara flat-hyphen.
+
+### Test (compound-sibling vs BEM-element)
+
+> "Skulle detta block fungera om jag tar bort dess parent-block?"
+> - Ja, det är ett fristående koncept → sibling-block (flat-hyphen OK)
+> - Nej, det är inre struktur av parent → BEM-element (`__`-syntax krav)
+
+### Exempel
+
+Rätt (siblings, kan användas separat):
+- `.hub-card` + `.hub-list` + `.hub-category` (paketets hub-card.css)
+- `.swipe-stack` + `.swipe-card` + `.swipe-actions` + ... (paketets swipe-stack.css)
+- `.form-card` + `.form-section` + `.form-group` (paketets form.css)
+
+Rätt (BEM-element, inre struktur):
+- `.hub-card__icon` (inom .hub-card)
+- `.swipe-card__title` (inom .swipe-card)
+- `.score-breakdown__dim-row` (inom .score-breakdown)
+- `.triage-card__source` (inom .triage-card)
+
+Fel (flat-hyphen för inre struktur):
+- `.score-dim-row` (skulle varit `.score-breakdown__dim-row`)
+- `.triage-source` (skulle varit `.triage-card__source`)
+- `.source-numbers` (skulle varit `.source-stats__numbers`)
+
+## Migration genomförd 2026-05-12
+
+Sprint BEM-2 + BEM-3 i Jubb migrerade 18 flat-hyphen-klasser till
+strikt BEM via `scripts/migrate_bem.py`:
+
+**BEM-2 (Jubb commit `21840ec`):**
+- `.score-dim-row/-label/-value` → `.score-breakdown__dim-row/-label/-value`
+- `.source-row/-numbers/-int/-dis` → `.source-stats__row/-numbers/-int/-dis`
+
+**BEM-3 (Jubb commit `c371f56`):**
+- `.triage-source/-title/-meta-row/-why/-detail-link` → `.triage-card__*`
+- `.triage-dismiss/-save/-interest` → `.triage-btn--*`
+- `.banner-triage*` → `.triage-banner` + `__text/__cta`
+
+Verifiering via `migrate_bem.py verify` (0 träffar gamla namn).
+Pytest 429 pass varje sprint. Class-maps committade som
+`scripts/class_map_bem2.yaml` + `scripts/class_map_bem3.yaml` för
+spårbarhet.
+
+## Tier D-undantagskatalog (dokumenterade flat-hyphen-block-familjer)
+
+Se `references/02-components.md` "Tier D-undantagskatalog"-sektionen
+för komplett lista. Två kategorier:
+
+### Paketets dokumenterade undantag
+- `.tooltip-wrapper` (compound block parent till `.tooltip`)
+- `.offline-wrap/-icon/-title/-text` (compound, alla 4 används tillsammans)
+- `.kv-budget-header/-body` (compound, lyfta från Ekonom utan rename
+  för template-kompatibilitet)
+
+### Ekonom Tier D (Sprint G 2026-05-09)
+- `.cat-bar-*` (7 klasser)
+- `.equity-bar-*` (6 klasser)
+- `.budget-bar-*` (5 klasser)
+- `.cat-tx-*` (6 klasser)
+
+Total: 7 paket-undantag + 24 Ekonom Tier D = 31 dokumenterade undantag.
+
+**Inga nya Tier D-poster utan ADR-beslut.**
+
+## Consequences
+
+**Bra:**
+- LLM-sessioner kan applicera regel 11 entydigt via test:en
+- Future flat-hyphen-inner-element fångas som regelbrott
+- Tier D-katalog är frusen lista, inte växande
+- Tooling (`scripts/migrate_bem.py`) kan användas igen för app-domain-
+  klasser som ackumuleras över tid
+
+**Trade-off:**
+- Existerande Ekonom Tier D-klasser förblir flat-hyphen. Migrera dem
+  retroaktivt skulle ge ingen visuell vinst men kostar template-byten
+  och risk för regression. Sprint G-rationale (2026-05-09) håller.
+- Jubbs `jubb.css` har fortfarande sibling-block-familjer (hour-heatmap,
+  radar-indicator, mode-toggle, signal-badge, job-list/job-card) som
+  passerar testen som genuint fristående siblings. Dokumentation pass
+  i BEM-6 listar dessa explicit i `02-components.md`.
+
+## References
+
+- Jubb commit `21840ec` (BEM-2: score-breakdown + source-stats)
+- Jubb commit `c371f56` (BEM-3: triage.css)
+- klodd-ds commit (denna ADR)
+- `references/03-quality-bar.md` regel 11
+- `references/02-components.md` Tier D-undantagskatalog
+- ADR `0009-no-flat-components-css.md` (besläktad, paket-vs-app-domain-separation)
+- ADR `0010-collapsible-block-rename.md` (besläktad, BEM-konvertering i paketet)

package/references/04-locked-decisions/0012-stylelint-bem-enforcement.md

@@ -0,0 +1,117 @@
+# 0012 - Stylelint BEM-enforcement via CI
+
+## Status
+Locked.
+
+## Context
+
+Regel 11 + ADR 0011 etablerade strikt BEM-element-syntax för inre
+struktur av compound-blocks. Enforcement var dock enbart mänsklig
+disciplin - inget automatiserat verktyg fångade regel-brott innan
+commit. Future-CC kunde introducera flat-hyphen-inner-class utan
+att CI flaggade det.
+
+Sprint BEM-2/3/6 (2026-05-12) migrerade 23 klasser i Jubb manuellt.
+Utan CI-enforcement skulle motsvarande drift kunna återinföras i
+nästa sprint utan att fångas.
+
+## Decision
+
+Stylelint configurerad i alla repos (klodd-ds + Jubb + Ekonom) med
+`selector-class-pattern`-regel som enforce BEM-syntax mekaniskt.
+
+### Regex-pattern
+
+```
+^[a-z][a-z0-9]*(-[a-z0-9]+)*(__[a-z0-9]+(-[a-z0-9]+)*)?(--[a-z0-9]+(-[a-z0-9]+)*)?$
+```
+
+Matchar:
+- `.block` (lowercase, kebab-case)
+- `.block-with-dashes` (compound block-namn)
+- `.block__element`
+- `.block--modifier`
+- `.block__element--modifier`
+- `.block-name__element-name--modifier-name` (compound på alla nivåer)
+
+Fångar (block):
+- PascalCase / camelCase (`.BadCapital`)
+- snake_case (`.block_with_underscores`)
+- Numerisk start (`.123-numeric`)
+- Dubbel-`__` (`.block__elem__nested`)
+- Dubbel-`--` (`.block--mod1--mod2`)
+- Trailing dash / underscore
+
+### CI-integration
+
+GitHub Actions workflow (`.github/workflows/stylelint.yml`) i alla
+tre repos kör `npm run lint:css` på push + PR mot main. Misslyckad
+lint blockerar merge / deploy.
+
+### Tier D-undantag
+
+Eftersom regex tillåter compound-block-namn (`.cat-bar-row`,
+`.tooltip-wrapper`) kräver dokumenterade Tier D-undantag inga
+`/* stylelint-disable */`-kommentarer. Regex matchar dem som
+"compound block". Begränsning: stylelint kan inte mekaniskt skilja
+på "dokumenterat Tier D" vs "nytt brott av samma typ".
+
+För strikt enforcement av Tier D-katalogen krävs custom plugin
+(framtida arbete) som korsreferrerar 02-components.md. Sprint 10-1
+levererar BEM-SYNTAX-enforcement, inte semantisk-Tier-D-enforcement.
+
+## Konfigurations-detaljer
+
+**Stäng av** (irrelevanta code-style-regler från stylelint-config-standard):
+- `lightness-notation`, `color-function-notation`, `alpha-value-notation`
+- `declaration-block-single-line-max-declarations`
+- `declaration-block-no-shorthand-property-overrides` (override-intent
+  i overlay.css)
+- Diverse `*-empty-line-before`-regler
+
+**Behåll**:
+- `selector-class-pattern` (BEM-regex) - huvudregel
+- `color-no-invalid-hex`
+- `no-duplicate-at-import-rules`
+- `comment-no-empty`
+- `no-invalid-double-slash-comments`
+
+## Consequences
+
+**Bra:**
+- Future-CC får CI-error vid BEM-syntax-brott
+- Regression-prevention för BEM-2/3/6-migrationen
+- Mekanisk enforcement minskar dependence på mänsklig review
+
+**Trade-off:**
+- Tier D vs nytt-brott skillnaden är inte mekaniskt fångad. Kräver
+  fortfarande mänsklig kontroll mot 02-components.md Tier D-katalog.
+- Stylelint-config replikeras i tre repos (klodd-ds + Jubb + Ekonom).
+  Migration till shared `@klodd/ds/stylelint-config` möjlig framöver
+  om underhåll blir issue.
+- Code-style-regler från stylelint-config-standard avstängda för att
+  inte blockera på icke-BEM-violations.
+
+## Setup-resultat 2026-05-12
+
+Audit-resultat efter installation:
+- **klodd-ds**: 0 BEM-violations (alla 37 komponentfiler + base/
+  + utilities passerar)
+- **Jubb**: 0 BEM-violations efter BEM-2/3/6-migrationen
+- **Ekonom**: 0 BEM-violations (Tier D-klasser tillåtna som compound)
+
+Test av regelns enforcement med medvetna brott:
+- `.BadCapital` → fångad
+- `.block_with_underscores` → fångad
+- `.123-numeric` → fångad
+- `.block__elem__nested` → fångad
+- `.block--mod1--mod2` → fångad
+
+## References
+
+- ADR 0011 (strikt BEM-elementsyntax) - regel 11-skärpning
+- `references/03-quality-bar.md` regel 11
+- `references/02-components.md` Tier D-undantagskatalog
+- `.stylelintrc.json` i alla tre repos
+- `.github/workflows/stylelint.yml` i alla tre repos
+- Jubb commits 21840ec, c371f56, 0bd1f97 (BEM-2/3/6-migration)

package/references/AUDIT-VISUAL-COHERENCE-2026-05-12.md

@@ -0,0 +1,216 @@
+# Visual Coherence Audit - 2026-05-12
+
+Full systemaudit av Jubb (jubb.klodd.io) och Ekonom (ekonom.klodd.io)
+mot målet "homogent designuttryck, slaviskt följt". 17 vyer
+auditerade via Chrome MCP javascript_tool layout-extraction.
+
+iPhone 14 Pro Max viewport (430x932).
+
+## Auditerade vyer (17)
+
+**Jubb (7):** /, /jobb, /triage, /insikter, /installera, /korningar
+**Ekonom (10):** /avstamning, /privat, /bolanet, /jag, /jag/abonnemang,
+/import, /granskning, /kategorier, /installningar, /installningar/{vart-hushall,
+var-bostad, auto-kategorisering, data}
+
+## Sammanställning: 5 kritiska brott
+
+### 1. Border-radius-kaos (11+ distinkta värden)
+
+Systemet använder **11+ olika BR-värden**:
+
+| Värde | Använt på |
+|---|---|
+| 2px | split-bar-segments |
+| 4px | mini-progress-bars |
+| 6px | small-badges |
+| 8px | tab-bar__item |
+| 10px | button (.btn) |
+| 12px | stat-card, tab-bar, setting-row |
+| 14px | job-card, hub-card |
+| 16px | banner, swipe-card |
+| 20px | panel, form-card |
+| 50% | icon-circles, avatars |
+| 9999px | pills (chip, badge--neutral) |
+
+**Inkonsekvenser inom samma "card-typ"**:
+- panel BR=20, form-card BR=20 ✓ matchar
+- job-card BR=14, hub-card BR=14 ✓ matchar
+- stat-card BR=12, swipe-card BR=16, banner BR=16 - varför olika?
+- tab-bar BR=12, tab-bar__item BR=8 - inkonsekvent inom samma komponent!
+
+**Ögat fångar detta som "olika former"** även när varje val är token-driven.
+
+### 2. Shadow-användning bryter regel 10
+
+Regel 10 (quality-bar): "ENDAST `var(--shadow-card)` i hela systemet.
+Aldrig hierarkisk skugg-skala."
+
+**Brott funna på 4 vyer**:
+- Jubb /jobb (sheet/dialog rendered i DOM)
+- Jubb /triage (sheet)
+- Ekonom /jag (sheet)
+- Ekonom /import (sheet)
+
+Shadow-värde: `oklch(0.949679 0.0026593 none / 0.08) 0px 8px 16px 0px`
+
+Detta är `--shadow-float` (overlay-shadow). På dark-mode ger ljus
+shadow inverterad djupkänsla (ljust på mörkt = lyft, inte sänkt).
+
+**Calle's observation "märklig ljus skugga på mörk bakgrund" är detta**.
+
+### 3. Hero-padding ger 4px alignment-drift
+
+Paketets `hero.css` har `padding: 20px 4px 24px`. Detta 4px horizontal
+shift sätter hero-content på x=18 (i 430-viewport). Andra element
+(setting-list, panels) sitter på x=14.
+
+**Resultat**: hero-content och andra block är på olika vertikala
+linjer. Calle's "alignment-problem" exakt fångat.
+
+### 4. Font-size-spread varierar dramatiskt
+
+Per-vy distinkta font-sizes:
+
+| Vy | Antal sizes | Spread |
+|---|---|---|
+| Jubb /korningar | 3 | 13/14/17 (clean) |
+| Ekonom /granskning | 4 | 12/14/15/22 (clean) |
+| Jubb /jobb | 5 | 11/12/13/14/17 |
+| Jubb /insikter | 7 | 10-22 |
+| Ekonom /jag | 9 | 10-24 |
+| Ekonom /bolanet | 9 | 10-51.6 (!) |
+
+**Anomalier**:
+- `51.6px` på Bolanet - INTE i token-skala (--fs-N är heltal-pixlar)
+- `13.3333px` på 6 Ekonom-vyer - browser sub-pixel-rendering av %-baserad fs
+
+### 5. Hero-pattern är inkonsekvent
+
+- **Jubb /, /installera**: hero med siffer-display (fs-80 hero_amount)
+- **Jubb /jobb, /insikter, /korningar**: ingen hero, börjar direkt med panel/list
+- **Ekonom /avstamning, /privat, /bolanet, /kategorier**: hero med fs-22-32-headings
+- **Ekonom /jag**: ingen hero, börjar med profil-panel
+- **Ekonom /granskning**: minimal hero
+
+Ingen kanonisk hero-pattern. Varje vy uppfinner sin egen.
+
+## Sekundära observationer
+
+### Padding-rytm är spridd
+
+Distinkta padding-värden funna:
+`0/2/4/6/8/10/12/14/16/18/20/24` plus combinations (20/4/24, 16/18, ...).
+
+12 distinkta värden i en enda design-system. För många.
+
+### Container-klasser används parallellt
+
+Bag av "card-like" containers över systemet:
+- .card (paketet)
+- .panel (paketet)
+- .job-card (Jubb)
+- .swipe-card (paketet)
+- .stat-card (paketet)
+- .hub-card (paketet)
+- .form-card (paketet)
+- .banner (paketet)
+
+8 olika container-typer. Varje har egen BR/bg/padding.
+
+### Bolanet är värst för konsekvens
+
+Ekonom /bolanet har:
+- 9 distinkta font-sizes (inkl 51.6 som är off-token)
+- 7 distinkta border-radius-värden
+- 9 distinkta padding-värden
+- Banner med OKLCH bg (positive-tint) som avviker från andra paneler
+
+Värst-i-klass. Förmodligen hot-spot för Calle's "olika storlekar".
+
+## Fix-strategi (Sprint 2-4)
+
+Fyra fix-kategorier prioriterade efter ROI:
+
+### Quick-wins (Sprint 2)
+
+1. **Ta bort shadow på sheet/dialog**: paket-fix i overlay.css.
+   Använd surface-overlay-token istället för shadow för djup.
+   Estimat: 30 min + npm bump + 2 appar.
+
+2. **Fixa hero-padding alignment**: paket-fix i hero.css. Byt
+   `padding: 20px 4px 24px` till `padding: 20px 0 24px`.
+   Estimat: 15 min + bump.
+
+3. **Fixa Bolanet fs-51.6**: Ekonom-domain. Förmodligen
+   `font-size: clamp(...)` med fluid sizing som ger non-integer.
+   Estimat: 30 min audit + fix.
+
+4. **Lägg till spacing-rule på setting-list/footer-text**: 16px gap.
+   Paket-fix på .muted-footer-text. Estimat: 15 min + bump.
+
+### Medium-fixes (Sprint 3)
+
+5. **Konsolidera BR-skala till 4 värden**: 10/14/20 + 9999.
+   - Button = 10
+   - Stat-card/tab-bar/setting-row = 14 (lyfta från 12)
+   - Job-card/hub-card/swipe-card/banner/panel/form-card = 14 (lyfta
+     från 14/16/20 till en värde)
+   - Pills/avatars = 9999/50%
+
+   Faktiskt sänka radikalt: 10 + 14 + 9999 = bara 3 värden.
+
+   Estimat: 2-3h paket-fix + 1h re-audit visuellt.
+
+6. **Konsolidera padding-rytm till 5 värden**: 4/8/12/16/20.
+   Eliminera 6/10/14/18/24 från komponent-CSS.
+   Plus app-domain audit.
+
+   Estimat: 3-4h paket-fix + audit.
+
+### Kanonisering (Sprint 4)
+
+7. **Hero-doktrin**: en kanonisk hero-struktur med modifier-klasser
+   för varianter (.hero, .hero--amount, .hero--minimal).
+   Alla dashboards använder hero (eller medvetet skippa det).
+
+   Estimat: 2-3h doc + paket-update + app-migration.
+
+8. **Container-klassifikation**: matrix för när använda card vs
+   panel vs *-card. Etablera doktrin "panel = sektion-container,
+   card = klickbar enhet, hub-card = navigation-target".
+
+   Estimat: 1-2h doc.
+
+### Locked decisions (Sprint 5)
+
+9. **ADR 0013-visual-coherence-doctrine.md** locked.
+10. **DESIGN-LANGUAGE.md** i klodd-ds.
+11. **SKILL.md update** med 10/10 visuell + mekanisk status.
+
+## Datapunkter (för transparens)
+
+Räknat över alla 17 vyer:
+
+- **Unique BR-values**: 11
+- **Unique font-sizes**: 13 (inkl rounding)
+- **Unique padding-values**: 18 (kombinationer)
+- **Unique container-classes**: 8
+- **Vyer med shadow**: 4 av 17 (24%)
+- **Vyer med hero**: 8 av 17 (47%)
+
+Mätbar mål för 10/10 efter Sprint 2-4:
+- BR-values: 11 → 4
+- Font-sizes: 13 → 8 (matchande --fs-N-tokens)
+- Padding-values: 18 → 6
+- Vyer med shadow: 4 → 0 (regel 10 strikt)
+- Vyer med hero: standardiserat per dashboard-doktrin
+
+## Begränsningar
+
+- Endast mobile-viewport (430x932)
+- Endast dashboard-vyer, inte modal/sheet-interna views
+- Sheets/dialogs auditerade i DOM-state, inte open-state
+- Animation/transition inte auditerade
+- Tap-target visuellt verifierat på job-card (44x44) men inte
+  systematiskt över hela systemet