@klodd/ds 3.14.13 → 3.15.0

package/references/DESIGN-LANGUAGE.md

@@ -0,0 +1,305 @@
+# Klodd Design Language
+
+Konkreta regler för **visuell koherens** över Klodd-ekosystemet. Token-
+arkitekturen (`01-tokens.md`) och komponent-API (`02-components.md`)
+specificerar **vad** som finns; denna fil specificerar **hur** komponenter
+ska användas tillsammans för homogen design-uttryck.
+
+**Grundprincip:** rytm > flexibilitet. Begränsade val ger visuell
+koherens. Varje element i samma kategori ska kunna bytas ut mot ett
+annat utan att layout-rytm bryts.
+
+Etablerad 2026-05-12 baserat på audit av 17 vyer (se
+`AUDIT-VISUAL-COHERENCE-2026-05-12.md`).
+
+## 1. Border-radius-skala (fem värden)
+
+**Regel:** all border-radius i komponent-CSS ska vara EN av:
+
+| Värde | Token | Användning |
+|---|---|---|
+| 4px | `--radius-4` | Thin-bars: progress, skeleton-line, split-bar-segment |
+| 10px | `--radius-10` | Button, inputs, tab-bar__item, small-action-button |
+| 14px | `--radius-14` | All cards/containers: card, panel, hub-card, job-card, swipe-card, banner, form-card, stat-card, list-row, setting-row, toast, dialog, sheet, collapsible, offline-wrap, sheet-content fields |
+| 50% | (calculated) | Avatars, icon-circles, toggle-thumb |
+| 9999px | `--radius-full` | Pills: badge, chip, status-pill, dot-separator, score-pill |
+
+**Förbjudet:** 2px, 6px, 8px, 12px, 16px, 18px, 20px, 22px, 24px på
+komponent-element. (Existerar som tokens men ska inte appliceras
+direkt på BR i komponent-CSS efter denna konsolidering.)
+
+**Rationale:** ögat skiljer på fem kategorier: thin-bar, button,
+container, circle, pill. 11+ värden ger visuell brus utan
+informations-värde. Calle's audit-observation "olika former" var
+denna BR-spridning.
+
+**Migration-not:** existerande paket-komponenter med BR=6/8/12/16/20/24
+flyttas till närmaste av de fem. Sprint 3b 2026-05-12 genomförde
+migrationen i paketet. App-domain-CSS följer samma regel.
+
+## 2. Shadow-policy (restriktiv)
+
+**Regel:** shadow används i tre exakt-definierade kontexter:
+
+| Kontext | Värde | Rationale |
+|---|---|---|
+| Modaler, sheets, dropdowns (overlay-elementer) | `box-shadow: none` | Dark-mode: surface-overlay + border ger djup. Shadow på mörk bg ger inverterad djupkänsla. |
+| iOS-style active-state-indikatorer (toggle-thumb, active-tab-pill) | `var(--shadow-card)` | Fysisk thumb-feel. Motiverat per regel 10. |
+| Allt annat | `box-shadow: none` | Default. |
+
+**Förbjudet:**
+- `--shadow-float`, `--shadow-resting`, `--shadow-raised`-tokens
+  utöver `--shadow-card`. (Existerar som alias - candidate för
+  borttagning i Sprint 3b.)
+- Hardkodade `box-shadow` med oklch eller rgba
+- Shadow på panel, card, hub-card, stat-card, banner, form-card
+  (de är inom-flow-element, hierarki via surface-tokens)
+- Shadow på bottom-nav, toast (inom-flow + backdrop-filter räcker)
+
+**Dark-mode-rationale:** ljus shadow på mörk bg ger inverterad
+djupkänsla (ljust = lyft, inte sänkt). Använd surface-color-hierarki
+istället: `--surface-page < default < raised < overlay`.
+
+## 3. Page-toppar: två separata patterns
+
+**Regel:** två väldefinierade patterns för page-toppar - hero och
+page-header. Välj baserat på purpose, inte preferens.
+
+### Pattern A: `.hero` (dashboard med metric)
+
+För dashboards där primär-data är en STOR siffer-display.
+
+```html
+<section class="hero">
+  <p class="hero__label">SEKTION-LABEL</p>
+  <p class="hero__amount">{stort-värde}</p>
+  <p class="hero__meta">{kontextuell-info}</p>
+  <div class="hero__actions">
+    <button class="btn btn--primary">{primär-action}</button>
+  </div>
+</section>
+```
+
+`.hero__amount` är fs-80 (siffer-display). `.hero__amount--card`
+(fs-40) för hero inom panel. `.hero__amount--fluid` (clamp 40-80vw)
+för responsiv siffer-display.
+
+Hero har `padding: 20px 0 24px` (alignment med övriga container-element).
+
+### Pattern B: `.page-header` (utility-page med titel)
+
+För pages utan primär-metric, bara navigation-kontext.
+
+```html
+<div class="page-header">
+  <h1 class="page-title">{Titel}</h1>
+  <p class="page-subtitle">{Beskrivning}</p>
+</div>
+```
+
+`.page-title` är fs-22 (heading-size). `.page-subtitle` är fs-13
+muted. Page-header har `display: flex` med space-between för
+sidoplacerade actions vid behov.
+
+### När använda vilken
+
+| Vy-typ | Pattern |
+|---|---|
+| Dashboard med primär-metric | `.hero` |
+| Lista-vy med titel | `.page-header` |
+| Settings-hub | `.page-header` |
+| Detalj-vy med metric | `.hero` (inom panel: `.hero--card`) |
+| Form-page | `.page-header` |
+
+### Konkret per app
+
+- **Jubb /, /installera**: `.hero` (job-count är primär-metric)
+- **Jubb /jobb, /korningar, /insikter**: `.page-header` (list-vyer)
+- **Jubb /triage**: ingen page-topp (swipe-stack är huvudobjekt)
+- **Ekonom /avstamning, /privat, /bolanet, /kategorier**: `.hero`
+  (saldo/utgifter/equity är primär-metric)
+- **Ekonom /jag**: `.page-header` (profil-vy, ingen metric)
+- **Ekonom /installningar, /granskning, /import**: `.page-header`
+- **Ekonom /jag/abonnemang**: `.page-header`
+
+### Gemensam spacing-doktrin
+
+Båda patterns följer alignment-regel sektion 8: content på `x = 14`
+(main-padding-left). Ingen inner horizontal padding på top-level
+container (hero, page-header).
+
+### Förbjudet
+
+- Blanda `.hero` och `.page-header` i samma vy
+- Använda `<div>` med ad-hoc styling istället för en av de två
+  patterns
+- Hardkodad font-size för titel-element (använd `.hero__amount`
+  eller `.page-title`)
+
+## 4. Padding-rytm (sex värden)
+
+**Regel:** all padding i komponent-CSS ska vara EN av:
+
+| Värde | Token | Användning |
+|---|---|---|
+| 4px | `--space-4` | Mini-gaps, badge inner, tab-spacing |
+| 8px | `--space-8` | Standard gap, icon-margin |
+| 12px | `--space-12` | List-row vertical, button-internal |
+| 16px | `--space-16` | Card internal, panel internal, hero |
+| 20px | `--space-20` | Section gap, hero-internal vertical |
+| 24px | `--space-24` | Major section break |
+
+**Förbjudet i komponent-CSS:** 2, 6, 10, 14, 18, 22, 28, 32-värden
+direkt. (Finns som tokens men reserverat för layout-grid och spacing
+mellan section-block, inte inom komponenter.)
+
+**Sammansatta padding (TRBL)**:
+- Symmetric preferred: `padding: 16px` ✓
+- Vertical-horizontal: `padding: 12px 16px` ✓
+- Asymmetric only with rationale: `padding: 20px 0 24px` (hero) -
+  kommentar med motivering krävs
+
+## 5. Font-size-skala (åtta värden)
+
+**Regel:** font-size i komponent-CSS ska vara EN av token-skalan:
+
+| Token | Användning |
+|---|---|
+| --fs-11 | Meta-text, time-stamps |
+| --fs-12 | Default body, list-row-text |
+| --fs-13 | Card-body, secondary |
+| --fs-14 | Primary body, button-text |
+| --fs-17 | Subtitle, panel-title |
+| --fs-22 | Heading, section-title |
+| --fs-32 | Large-display, card-hero |
+| --fs-80 | Page-hero amount |
+
+**Förbjudet:** 15px, 18px, 20px, 24px, 40px, 64px på text-content.
+(Token-värden finns men ska användas selektivt och inom
+specifika komponenter.)
+
+**Förbjudet i app-domain-CSS:**
+- `clamp()`-baserade font-sizes som ger non-integer rendering
+- `font-size: 13.3333px` (browser sub-pixel av %-baserat värde)
+- Hardkodade `font-size: 14px` utan token
+- `font-size: 51.6px` (Bolanet) - off-token värde
+
+## 6. Container-klassifikation (vilket är vad)
+
+**Regel:** välj rätt container baserat på funktion:
+
+| Komponent | När använda | Inte använda för |
+|---|---|---|
+| `.card` | Klickbar enhet med titel + body | Statisk info-panel |
+| `.card--interactive` | Card med hover/press-feedback | Static-card |
+| `.panel` | Ramad sektion med titel, statisk innehåll | Klickbar |
+| `.hub-card` | Settings-hub navigation-target | Generic listrad |
+| `.job-card` (Jubb) | Job-listing enhet | Generic card |
+| `.swipe-card` | Tinder-stil swipeable card | Static info |
+| `.stat-card` | Single-metric display (siffra + label) | Multi-content |
+| `.banner` | Bred info-rad i flow | Action card |
+| `.form-card` | Form-wrapper | Generic content |
+| `.list-row` | Generic list-rad med ikon + body + amount | Settings-rad |
+| `.setting-row` | Tap-to-edit settings-rad | Klickbart kort |
+
+**Bias-toward-panel:** vid osäkerhet, använd `.panel`. Det är default-
+container.
+
+## 7. Spacing-rytm mellan block
+
+**Regel:** vertikalt spacing mellan distinkta block:
+
+- Mellan topbar och första block: `margin-bottom: 16` på topbar
+- Mellan section-block (panel, hero, section): `margin-bottom: 14`
+- Mellan list-row (samma list): `margin: 0` (border-top för separator)
+- Mellan hub-card-list-items: `margin-bottom: 12`
+- Mellan section och footer-text: `margin-top: 16` på footer
+
+**Förbjudet:** beroende på `gap`-property på parent när siblings har
+egna `margin-bottom`. Välj en mekanism per kontext.
+
+## 8. Alignment-regler
+
+**Regel:** alla primära block-content sitter på samma horizontal-x.
+
+- Main har `padding: 16px 14px 84px` (top-right-bottom-left). Content
+  startar på `x = 14`.
+- Container-block (panel, card, hero, hub-card) sitter på `x = 14`
+  (no extra margin).
+- Inom container, text-content sitter på `x = 14 + container-inner-padding`.
+- Hero ska INTE ha asymmetrisk horizontal padding (förbjudet:
+  `padding: 20px 4px 24px`). Tillåtet: `padding: 20px 0 24px` eller
+  `padding: 20px`.
+
+## 9. PWA-specifika konventioner
+
+### Tap-targets
+
+- Alla interaktiva element MÅSTE vara minst 44x44px (WCAG 2.5.5).
+- Buttons: `min-height: var(--touch-min)` (= 44).
+- List-rows: `padding: 14px 0` minimum (= 50px height med text-line).
+- Icon-buttons: `width: 44px; height: 44px`.
+
+### Mobile-first
+
+- Default-styles är mobile (375-430 viewport).
+- Tablet (768+) och desktop (1024+) är progressive enhancements.
+- Test alltid på iPhone 14 Pro Max (430x932) som baseline.
+
+### Safe areas
+
+- `padding-top: calc(var(--safe-top) + 16px)` på main för iOS-notch.
+- `padding-bottom: var(--bottom-nav-clearance)` (= 84px) för fixed
+  bottom-nav.
+
+### iOS-specifika
+
+- Inputs: `font-size: 17px` minimum (anti auto-zoom).
+- Touch-feedback: `:active` med `transform: scale(0.97)` + spring-easing.
+- Hover wrappas i `@media (hover: hover) and (pointer: fine)`.
+
+## 10. Färg-konvention
+
+**Regel:** alla bakgrundsfärger via semantic surface-tokens:
+
+```
+--surface-page (sidens bg, lägst)
+--surface-default (sektioner, list-rows)
+--surface-raised (kort, paneler - en steg upp)
+--surface-overlay (modaler, popovers)
+--surface-hover (:hover bg)
+--surface-active (:active bg)
+--surface-sunken (inputs - LÄGRE än page för iOS-stil)
+```
+
+**Förbjudet i komponent-CSS:**
+- Hardkodade hex/rgb-värden
+- `var(--gray-N)`, `var(--blue-N)`, `var(--plum-N)` direkt (bara i
+  primitives + apps/-filer)
+- `rgba()` med alpha - använd `color-mix(in oklch, ...)` eller
+  `--accent-aN`-tokens
+
+## 11. Enforcement-status
+
+Mekanisk enforcement via stylelint (Sprint 10-1) fångar BEM-syntax-
+brott men INTE design-rule-brott. Visuell coherence är fortfarande
+human-disciplin + framtida custom plugin.
+
+Future custom stylelint-plugin kan enforce:
+- BR-value är en av {10, 14, 9999}
+- Font-size är en av token-skalan
+- Padding-värden begränsade till de 6 listade
+- Shadow forbidden utöver `--shadow-card`
+
+Tills sådan plugin finns: visual-coherence är CC-disciplin baserat
+på denna fil.
+
+## 12. När ändra regler
+
+Denna fil är **locked**. Ändringar kräver:
+1. ADR i `references/04-locked-decisions/` med rationale
+2. Audit-pass av berörda vyer
+3. Migration av befintliga komponenter till nya regeln
+4. Update av ADR 0013 (visual-coherence-doctrine)
+
+Inga ad-hoc-ändringar utan ADR-process.