@simscloud/design 0.1.0 → 1.0.0

package/README.md

@@ -0,0 +1,119 @@
+# @simscloud/design — SIMS design system
+
+The single source of visual truth for SIMS: design **tokens** (`tokens.css`), a **Tailwind
+preset** (`tailwind-preset.js`), and self-hosted **fonts** (`fonts/`). Consumed by the app
+directly (workspace) and by the landing/hosted repos as a version-pinned package (UI.md §2).
+
+This document is the **D1 visual spec** (issue #70): the finalized language plus the
+accessibility rules — **contrast ratios** and **minimum tap-target sizes** — that the atoms
+in `@simscloud/ui` and every later screen (D2–D6) must honor.
+
+## Voice & audience
+
+German-first, _einfache Sprache_, "UpKeep but simpler". The primary users are non-technical
+Spitex staff on **tablets and phones**. Two consequences are non-negotiable:
+
+- **Contrast** — body text meets **WCAG AA (≥4.5:1)**; large text / non-text UI ≥3:1.
+- **Touch** — interactive controls are **≥44×44px** (`--tap-target-min`, WCAG 2.5.5).
+
+## Brand & logo
+
+The mark lives in `misc/brand/logo/` (four SVGs); render it through the `@simscloud/ui`
+`Logo` atom (`src` is passed in, so this package stays asset-pipeline-free).
+
+| File | Use |
+|---|---|
+| `logo_text_color.svg` | default — wordmark on light surfaces |
+| `logo_text_white.svg` | wordmark on dark / brand (navy) surfaces |
+| `logo_notext_color.svg` | compact mark (favicon, tight headers) on light |
+| `logo_notext_white.svg` | compact mark on dark / brand |
+
+Brand anchor: **navy `#000059`** (`--navy-600`), matching the logo.
+
+## Color tokens
+
+Two layers (UI.md §2.5): **primitives** (raw values, never used directly) → **semantic**
+(intent; components use only these). Re-theming = swap the semantic layer; a commented dark
+theme in `tokens.css` proves the door is open.
+
+| Semantic | Role |
+|---|---|
+| `brand` / `brand-strong` / `brand-soft` / `on-brand` | primary actions, hover, tint, text-on-brand |
+| `bg` / `surface` / `surface-muted` | page, panel, subtle section |
+| `text` / `text-muted` / `heading` / `text-inverse` | body, secondary, titles, on-dark |
+| `line` / `ring` | borders / focus ring |
+| `success` / `warning` / `danger` | **fill/border/icon only** |
+| `success-strong` / … | **status as text** (AA-safe) + solid status-button bg |
+| `success-stronger` / … | solid status-button **hover** |
+
+> ⚠️ **Status colors:** the bright `success`/`warning`/`danger` fills fail AA as text
+> (`warning` is ~2.1:1 on white). For any status **text**, use the `*-strong` shades —
+> e.g. `text-danger-strong`. The bright fills are fine for left accents, icons, and chips.
+
+## Contrast ratios (verified, WCAG)
+
+| Foreground | Background | Ratio | AA |
+|---|---|---|---|
+| `text` #0f172a | `bg` #ffffff | 17.85:1 | ✅ |
+| `text` #0f172a | `surface` #f6f8fb | 16.78:1 | ✅ |
+| `text-muted` #5b6776 | `bg` | 5.76:1 | ✅ |
+| `text-muted` #5b6776 | `surface` | 5.41:1 | ✅ |
+| `heading` #000037 | `bg` | 19.90:1 | ✅ |
+| `on-brand` #fff | `brand` #000059 | 18.35:1 | ✅ |
+| `brand` #000059 (links/ghost) | `bg` | 18.35:1 | ✅ |
+| `success-strong` #15803d | `bg` / `surface` | 5.02 / 4.71 | ✅ |
+| `warning-strong` #b45309 | `bg` / `surface` | 5.02 / 4.72 | ✅ |
+| `danger-strong` #b91c1c | `bg` / `surface` | 6.47 / 6.08 | ✅ |
+| `on-brand` #fff | `danger` #dc2626 (button) | 4.83:1 | ✅ |
+
+(Recompute after any palette change — the brand navy is very dark, so the perennial risk is
+the status colors, not the brand.)
+
+## Typography
+
+Self-hosted **DejaVu Sans** (400/700), so it renders identically on every OS. German strings
+run ~30% longer than English → **never shrink body below 16px**, and let text wrap.
+
+| Role | Class | Notes |
+|---|---|---|
+| Display | `text-4xl font-bold` | hero, rare |
+| Screen title (h1) | `text-3xl font-bold text-heading` | |
+| Section (h2) | `text-2xl font-semibold` | |
+| Card/group title (h3) | `text-xl font-semibold` | |
+| **Body** | `text-base` (16px) `leading-relaxed` | the floor for readable copy |
+| Meta / secondary | `text-sm text-text-muted` | |
+| Caption | `text-xs` | avoid for primary content |
+
+## Spacing, radii, elevation
+
+- **Spacing** — the Tailwind **4px base scale** (`1`=4px … `4`=16px, `6`=24px, `8`=32px).
+  Card padding `p-8`, list gaps `gap-3`/`gap-4`, section rhythm `space-y-6`/`8`.
+- **Radii** — `rounded-md` (controls), `rounded-xl` (cards), `rounded-full` (pills/spinner).
+- **Elevation** — `shadow-1` (resting card), `shadow-2` (hover/raised), `shadow-3` (overlays);
+  navy-tinted so shadows read as brand, not grey.
+
+## Focus & tap targets
+
+- **Focus** — visible **2px ring** in `ring` (navy): `focus-visible:outline-2
+  focus-visible:outline-offset-2 focus-visible:outline-ring`. Never remove focus styles.
+- **Tap target** — `min-h-tap` / `min-w-tap` (44px). Baked into `Button`; D2 nav and any new
+  interactive control must meet it too.
+
+## Atom states (`@simscloud/ui`)
+
+| Atom | States |
+|---|---|
+| **Button** | variants `primary` / `secondary` / `ghost` / `success` / `warning` / `danger` (status buttons use the AA-safe `-strong` bg + `-stronger` hover) · states default · hover (mouse) · press (same emphasis shade — visible on touch; a mouse click also darkens slightly) · focus-visible (ring) · disabled · **loading** (spinner + `aria-busy`) · sizes md/lg · ≥44px. Hover/press are pointer-event-driven (not CSS `:hover`/`:active`) for consistent touch behavior across browsers. |
+| **Card** | resting (`shadow-1`) · **interactive** (hover lift to `shadow-2`; wrap in a real button/link for keyboard a11y) |
+| **Alert** | `info` / `success` / `warning` / `danger` — left accent (bright fill) + AA-safe `*-strong` title; `role="alert"` (warning/danger) vs `role="status"` (info/success) |
+| **Spinner** | sizes sm/md/lg; `role="status"` + localizable `aria-label` |
+| **Logo** | wordmark/mark × color/white via `src` |
+| **Input** | _deferred — added when the first form screen needs it (D5 / #74)._ |
+
+## Open / deferred
+
+- **Input atom** — intentionally not built yet (added with the first form, #74).
+- **Dark mode & per-tenant brand** — not enabled; the semantic-variable structure keeps the
+  door open (swap the semantic layer, zero atom changes).
+- **Approved key-screen mockups** — the subjective visual direction (#70 part A) is settled
+  with stakeholders separately; this doc covers the objective token/accessibility spec.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simscloud/design",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Shared SIMS design tokens — CSS variables, Tailwind preset, and web fonts. Framework-agnostic (no React).",
   "license": "AGPL-3.0-only",
   "repository": {

package/tailwind-preset.js

@@ -16,51 +16,102 @@
 
 /** @type {import('tailwindcss').Config} */
 export default {
+  future: {
+    // Gate `hover:` styles to real pointer devices (`@media (hover: hover)`), so a touch tap
+    // doesn't leave a "stuck" hover state until you tap elsewhere. (Default in Tailwind v4.)
+    hoverOnlyWhenSupported: true,
+  },
   theme: {
     extend: {
       colors: {
         brand: {
-          DEFAULT: 'var(--color-brand)',
-          strong: 'var(--color-brand-strong)',
-          soft: 'var(--color-brand-soft)',
+          DEFAULT: "var(--color-brand)",
+          strong: "var(--color-brand-strong)",
+          light: "var(--color-brand-light)",
+          soft: "var(--color-brand-soft)",
         },
-        'on-brand': 'var(--color-on-brand)',
+        "on-brand": "var(--color-on-brand)",
 
-        bg: 'var(--color-bg)',
+        bg: "var(--color-bg)",
         surface: {
-          DEFAULT: 'var(--color-surface)',
-          muted: 'var(--color-surface-muted)',
+          DEFAULT: "var(--color-surface)",
+          muted: "var(--color-surface-muted)",
         },
-        header: 'var(--color-header-bg)',
-        banner: 'var(--color-banner)',
-        overlay: 'var(--color-overlay)',
+        header: "var(--color-header-bg)",
+        banner: "var(--color-banner)",
+        overlay: "var(--color-overlay)",
 
         text: {
-          DEFAULT: 'var(--color-text)',
-          muted: 'var(--color-text-muted)',
-          inverse: 'var(--color-text-inverse)',
+          DEFAULT: "var(--color-text)",
+          muted: "var(--color-text-muted)",
+          inverse: "var(--color-text-inverse)",
         },
-        heading: 'var(--color-heading)',
+        heading: "var(--color-heading)",
 
-        line: 'var(--color-border)',
-        ring: 'var(--color-ring)',
+        line: "var(--color-border)",
+        ring: "var(--color-ring)",
 
-        success: 'var(--color-success)',
-        warning: 'var(--color-warning)',
-        danger: 'var(--color-danger)',
+        // DEFAULT = fill/border/icon; `strong` = accessible text + solid-button bg;
+        // `stronger` = that button's hover (all white-text-AA on the strong/stronger shades).
+        success: {
+          DEFAULT: "var(--color-success)",
+          strong: "var(--color-success-strong)",
+          stronger: "var(--color-success-stronger)",
+          soft: "var(--color-success-soft)",
+        },
+        warning: {
+          DEFAULT: "var(--color-warning)",
+          strong: "var(--color-warning-strong)",
+          stronger: "var(--color-warning-stronger)",
+          soft: "var(--color-warning-soft)",
+        },
+        danger: {
+          DEFAULT: "var(--color-danger)",
+          strong: "var(--color-danger-strong)",
+          stronger: "var(--color-danger-stronger)",
+          soft: "var(--color-danger-soft)",
+        },
       },
 
       fontFamily: {
-        sans: 'var(--font-sans)',
-        display: 'var(--font-display)',
+        sans: "var(--font-sans)",
+        display: "var(--font-display)",
       },
 
       borderRadius: {
-        sm: 'var(--radius-sm)',
-        md: 'var(--radius-md)',
-        lg: 'var(--radius-lg)',
-        xl: 'var(--radius-xl)',
-        full: 'var(--radius-full)',
+        sm: "var(--radius-sm)",
+        md: "var(--radius-md)",
+        lg: "var(--radius-lg)",
+        xl: "var(--radius-xl)",
+        full: "var(--radius-full)",
+      },
+
+      boxShadow: {
+        1: "var(--shadow-1)",
+        2: "var(--shadow-2)",
+        3: "var(--shadow-3)",
+      },
+
+      // Motion — one-shot success "pop" for the shared finish animation (FinishScreen · #73).
+      // Applied as `animate-finish-pop motion-reduce:animate-none`, so a `prefers-reduced-motion`
+      // viewer simply drops the pop and lands on the static, fully-visible success state.
+      keyframes: {
+        "finish-pop": {
+          "0%": { transform: "scale(0.6)", opacity: "0" },
+          "60%": { transform: "scale(1.06)", opacity: "1" },
+          "100%": { transform: "scale(1)", opacity: "1" },
+        },
+      },
+      animation: {
+        "finish-pop": "finish-pop 380ms cubic-bezier(0.2, 0.7, 0.3, 1) both",
+      },
+
+      // Minimum touch target (44px) → `min-h-tap` / `min-w-tap` on interactive atoms.
+      minHeight: {
+        tap: "var(--tap-target-min)",
+      },
+      minWidth: {
+        tap: "var(--tap-target-min)",
       },
     },
   },

package/tokens.css

@@ -44,15 +44,26 @@
   --gray-300: #cbd2de;
   --gray-400: #9aa3b2;
   --gray-500: #64748b;
+  --gray-550: #5b6776; /* muted text — passes AA on the surface bg (gray-500 falls just short) */
   --gray-600: #475569;
   --gray-700: #334155;
   --gray-800: #1e293b;
   --gray-900: #0f172a;
 
-  /* Support / status */
+  /* Support / status. The -500s are FILL/border/icon colors (not for body text — they fail
+     AA on white). The -700s are the accessible TEXT shades (≥4.7:1 on bg AND surface). */
   --green-500: #16a34a;
   --amber-500: #f59e0b;
   --red-500:   #dc2626;
+  --green-700: #15803d;
+  --amber-700: #b45309;
+  --red-700:   #b91c1c;
+  --green-900: #14532d; /* solid status-button hover — a clearly darker step from -700 */
+  --amber-900: #78350f;
+  --red-900:   #7f1d1d;
+  --green-50:  #f0fdf4; /* pale status tints — row/section wash behind -700 text (passes AA) */
+  --amber-50:  #fffbeb;
+  --red-50:    #fef2f2;
 
   /* Typography — DejaVu Sans (matches the logo wordmark; self-hosted, so it
      renders identically on every OS). The @font-face lives in the consuming
@@ -67,6 +78,14 @@
   --radius-xl:   1.5rem;
   --radius-full: 9999px;
 
+  /* Elevation — navy-tinted (rgb 0 0 40) so shadows read as part of the brand, not grey. */
+  --shadow-1: 0 1px 2px 0 rgb(0 0 40 / 0.06);
+  --shadow-2: 0 4px 12px -2px rgb(0 0 40 / 0.10);
+  --shadow-3: 0 12px 32px -8px rgb(0 0 40 / 0.16);
+
+  /* Minimum touch target (WCAG 2.5.5; tablets/phones are the primary surface). */
+  --tap-target-min: 2.75rem; /* 44px */
+
   /* ========================================================================
    * Layer 2 — SEMANTIC (light theme)
    * ===================================================================== */
@@ -74,6 +93,7 @@
   /* Brand */
   --color-brand:         var(--navy-600);
   --color-brand-strong:  var(--navy-800);
+  --color-brand-light:   var(--navy-400); /* lighter hover for the near-black primary button */
   --color-brand-soft:    var(--navy-50);
   --color-on-brand:      #ffffff;
 
@@ -87,7 +107,7 @@
 
   /* Text */
   --color-text:          var(--gray-900);
-  --color-text-muted:    var(--gray-500);
+  --color-text-muted:    var(--gray-550);
   --color-text-inverse:  #ffffff;
   --color-heading:       var(--navy-800);
 
@@ -95,10 +115,20 @@
   --color-border:        var(--gray-200);
   --color-ring:          var(--navy-600);
 
-  /* Status */
-  --color-success:       var(--green-500);
-  --color-warning:       var(--amber-500);
-  --color-danger:        var(--red-500);
+  /* Status. DEFAULT = fill/border/icon. *-strong = accessible text on light surfaces AND
+     the bg of solid status buttons (white text passes AA). *-stronger = those buttons' hover. */
+  --color-success:          var(--green-500);
+  --color-warning:          var(--amber-500);
+  --color-danger:           var(--red-500);
+  --color-success-strong:   var(--green-700);
+  --color-warning-strong:   var(--amber-700);
+  --color-danger-strong:    var(--red-700);
+  --color-success-stronger: var(--green-900);
+  --color-warning-stronger: var(--amber-900);
+  --color-danger-stronger:  var(--red-900);
+  --color-success-soft:     var(--green-50); /* subtle fill: import-wizard row wash, callouts */
+  --color-warning-soft:     var(--amber-50);
+  --color-danger-soft:      var(--red-50);
 }
 
 /* =============================================================================