# XNEURO — Design System

A design system for **XNEURO**, a neuro-health company, and its first product: a
**headache self-monitoring app** (頭痛ダイアリー / *zutsuu diary*) — a fully
personalized **PHR** (Personal Health Record) for headache patients on iPhone.

> **Heads-up — this is a v1 proposal.** XNEURO had **no prior brand, UI code, or
> Figma** when this system was built. The product context below is drawn directly
> from the source repo's requirements doc; the *visual* system (palette, type,
> components) is a grounded proposal, not an extraction from existing art. It's
> meant to be a strong, opinionated starting point that's easy to retune.

---

## What the product is

A self-monitoring **headache diary**. The patient records — with the *minimum
possible input burden* — **when, where, and how strongly** their head hurts, and
the app visualizes the pattern over time (intensity, frequency) so that a doctor
can grasp the patient's state at a glance during a consultation.

**Core jobs to be done**
- **Log a headache in tens of seconds** — one-tap-first. This is the #1 metric;
  if logging is slow, patients stop doing it.
- **Visualize pain** — intensity & frequency trends on a calendar and a chart.
- **Correlate with environment** — overlay barometric pressure / weather.
  WeatherKit auto-fetch is an optional Phase 1 feature, off by default if needed.
- **Share at the clinic** — a monthly summary + PDF the doctor can read fast.
- **Capture product feedback** — from Home, the patient can write free-text
  app-improvement requests without the app auto-sending them anywhere.

**Hard product constraints (shape the design)**
- **iPhone-native, local-first.** Symptom data is *sensitive personal information*:
  device lock + biometric unlock on launch + at-rest encryption. No cloud in Phase 1.
- **Not a medical device.** Record & visualize only — **no diagnosis or treatment
  recommendations** (regulatory: avoids 薬機法 medical-device classification).
- **Single patient (patient1).** Built for one person first; viewers are the
  patient + their doctor (in-person screen-share at first).
- **Japanese-first.** All UI copy is Japanese; design must handle JP typography.

**Roadmap (for context):** Phase 1 local diary + monthly summary + PDF →
Phase 2 live display to a doctor's iPad in-room → Phase 3 remote display in online
consults → Phase 4 (optional) synced cloud.

### A design insight that drives everything
Headache & migraine patients are frequently **photophobic** (light-sensitive),
often *during* the exact moments they need to log. So this system is deliberately
**low-glare**: no pure-white fields, no pure-black text, no alarming saturated
red, gentle contrast, large tap targets, and a calm motion language. Comfort is a
feature, not a finish.

---

## Sources

These informed the system. The reader may not have access, but they're recorded
so a future designer can go deeper:

- **GitHub — `shunxneuro/headache-app`** (private): https://github.com/shunxneuro/headache-app
  - `patient1/docs/requirements/product-requirements.md` — the product spec (the
    canonical artifact; it defines vision, scope, constraints, roadmap).
  - `patient1/体調管理チェックシート.xlsx` — a manual "health-condition check
    sheet" the patient used before the app. This file is the canonical reference
    for the monthly summary / PDF layout.
  - `CLAUDE.md` — generic engineering guidelines, not design-relevant.

> Explore `shunxneuro/headache-app` further to build more accurate designs — the
> requirements docs in `patient1/docs/requirements/` are the source of truth for
> scope and data model.

---

## CONTENT FUNDAMENTALS

How XNEURO writes. The product is **Japanese-first**, calm, and clinical-but-kind.

- **Language & voice.** Primary copy is **Japanese**. The voice is *gentle,
  plain, reassuring* — never clinical-cold, never cute. Think "a calm nurse,"
  not "a hospital form" and not "a chirpy wellness app."
- **Politeness register.** Default to soft **です・ます** (polite) for guidance and
  empty states ("記録を始めましょう" — *let's start recording*). Use bare nouns /
  体言止め for labels and data ("今日の記録", "強さ", "部位"). Avoid stiff
  honorific overload.
- **Person.** The app addresses the patient warmly but rarely says "あなた."
  It speaks *with* them ("記録しましょう"), and refers to their data as theirs
  ("あなたの頭痛の傾向") only when summarizing for the doctor.
- **Casing & Latin.** Brand is set **XNEURO** (all-caps wordmark). Latin UI labels
  (units, axis ticks, section tags) use UPPERCASE tracking for micro-labels
  ("HPA", "AM / PM", "NRS"), Title Case is avoided in JP context.
- **Numbers & units.** Numerals are **tabular**. Pain uses a 0–10 NRS *and* a
  4-step word scale (軽い / 中くらい / 強い / 激しい). Dates are JP format
  (6月1日(月)), times 24h (14:30). Pressure in hPa.
- **Tone in sensitive moments.** Security/consent copy is straightforward and
  calm, never scary: "記録は、この端末の中だけで暗号化して保存されます。"
- **Brevity.** Buttons are 1–4 chars where possible (記録 / 保存 / 共有 / 閉じる).
  Empty states are one warm sentence + one action. No walls of text.
- **No emoji** in product chrome. Headache locations and intensity are shown with
  the system's own schematic marks and the pain-color ramp — not 😣/🤕.
- **Never prescribe.** Copy never says "you should take medicine / see a doctor
  because…". It *reports and visualizes*; the human interprets. ("3月は強い頭痛が
  6回ありました" — a fact, not advice.)

**Examples**
- Onboarding: 「XNEURO へようこそ。頭痛を、いちばん軽い手間で記録します。」
- Quick-log title: 「いま、頭痛は？」 → buttons 軽い / 中くらい / 強い / 激しい
- Empty calendar: 「まだ記録がありません。最初の記録をしてみましょう。」
- Summary line: 「今月の頭痛日数 12日 ・ 平均の強さ 中くらい」
- Privacy: 「データは端末内で暗号化。あなたの許可なく外には出ません。」

---

## VISUAL FOUNDATIONS

- **Overall vibe.** Calm, clean, clinical-warm. A quiet instrument you trust at
  3am with a migraine. Generous whitespace, soft surfaces, one confident accent.
- **Color.** A single brand teal (`--brand #1C6E69`) — calm, medical, trustworthy
  — on warm-cool **mist neutrals** (canvas is `#EEF2F2`, never pure white).
  Primary text is a deep **teal-charcoal** (`#18302E`), never `#000`. The
  signature element is the **pain-intensity ramp**: 5 desaturated earth tones from
  cool grey (none) → sage → amber → terracotta → muted coral (very severe). It
  escalates *clearly* but never uses alarm-red — distress shouldn't add distress.
  A separate cool indigo (`--env-pressure`) is reserved for barometric overlays.
- **Type.** One family — **Zen Kaku Gothic New** (Japanese + Latin, calm humanist
  gothic), weights 400/500/700/900. One-family discipline mirrors native iOS (SF).
  Big data uses a heavy tabular numeral (`.t-numeral`); micro-labels use tracked
  uppercase Latin.
- **Backgrounds.** Flat, soft, low-glare. **No photographic backgrounds, no
  gradients-as-decoration, no textures.** The only gradients allowed are subtle
  *protection* scrims behind floating chrome and the soft fills behind charts.
  Surfaces are distinguished by tint + hairline, not heavy shadow.
- **Cards.** White (`--surface`) on mist canvas, radius `--r-lg (20px)`, hairline
  border `--line`, and a *soft low-contrast* shadow (`--sh-2`). Grouped lists use
  the iOS inset style (rounded container, hairline dividers). No colored
  left-border-accent cards.
- **Corner radii.** Soft and consistent: controls 14px, cards 20px, sheets 28px,
  chips/pills fully round. Nothing sharp-cornered; nothing cartoonishly round.
- **Borders & dividers.** Hairlines only (`1px var(--line)`), used sparingly.
  Selection is shown with the brand tint fill + a 2px brand ring, not heavy strokes.
- **Shadows / elevation.** Three soft steps (`--sh-1/2/3`) plus a sheet shadow.
  All low-opacity teal-tinted — feels like soft daylight, not a hard drop shadow.
  Bottom sheets cast upward (`--sh-sheet`).
- **Transparency & blur.** Used like iOS: translucent **frosted** bars
  (tab bar, nav bar, sheet backdrop) with `backdrop-filter: blur` + a faint tint,
  so content scrolls softly underneath. Backdrop scrim behind modals is a low
  teal-ink wash, not pure black.
- **Motion.** Calm and quick. Settle easing `--ease-out` (no bounce/overshoot —
  bounce reads playful, wrong for a medical tool). Sheets slide up `--dur (240ms)`,
  selections fade/scale subtly, charts draw in once. Respect reduced-motion.
- **Hover / press.** (Hover is rare — this is touch-first.) **Press** state =
  gentle scale-down (`0.97`) + slight darken to `--brand-press`; soft buttons
  darken their tint. No glow, no ripple.
- **Layout rules.** Fixed top nav (frosted) + fixed bottom tab bar (frosted),
  content scrolls between. A large circular **+ record** affordance is the one
  persistent primary action. Safe-area aware. Single-column, thumb-reachable
  primary actions in the lower third.
- **Imagery.** Minimal. Data *is* the imagery. Where a glyph is needed (head
  regions, weather) use simple schematic line marks in `--fg-2`, never photos,
  never 3D, never emoji.

---

## ICONOGRAPHY

- **System.** No bespoke icon font existed, so the system uses **Lucide**
  (https://lucide.dev) — open-source, **2px stroke, rounded line** icons. Their
  calm, even line weight matches the photophobia-aware, gentle character far
  better than filled or sharp icon sets. Loaded from CDN in the UI kits.
  **→ Substitution flagged:** Lucide is a stand-in for a future bespoke set. If
  XNEURO commissions custom icons, keep the 2px-rounded-line spec.
- **Sizing & color.** Icons render at 20px (inline / tab bar) and 24px (actions),
  stroke inherits `currentColor` — usually `--fg-2`, brand teal when active.
- **Schematic marks (product-specific).** Two glyph families are *part of the
  brand*, drawn as simple line schematics, not from an icon set:
  - **Head-region selector** — a realistic, neutral front-view head where the
    patient **drags a finger to paint** where it hurts (regions light up as a soft
    glow + targeting reticle as you pass over them) and **taps to toggle** any one
    off. Every region has a **left/right** variant (右の前頭部 / 左の前頭部, 右目の奥 /
    左目の奥, … plus 後頭部 and 首・肩 L/R via chips). This is a signature
    functional control, not decoration.
  - **Pain-intensity chips** — solid rounded swatches colored by the pain ramp,
    not faces/emoji.
- **Emoji & unicode.** **Not used** in product chrome. Unicode is used only for
  honest typographic glyphs (·, –, ℃, ↑↓ trend arrows, hPa).
- **Logo / wordmark.** `XNEURO` set in Zen Kaku Gothic New **900**, tracked
  `+0.04em`, in brand teal (or `--fg-on-brand` on teal). The "X" may carry a
  subtle node/neuron tick. See `/assets/xneuro-wordmark.svg`.

---

## Index / Manifest

Root files:
- **`README.md`** — this file (context, content, visual, iconography, manifest).
- **`SKILL.md`** — Agent-Skill front-matter so this can be used in Claude Code.
- **`colors_and_type.css`** — all design tokens (color, type, radius, shadow,
  spacing, motion) + semantic type classes. Import this in any XNEURO design.

Folders:
- **`assets/`** — logo / wordmark, app icon, and the head-region schematic.
- **`fonts/`** — `Apple_Braille.ttf` (user-uploaded; a braille/tactile-dot font,
  wired as `@font-face` but **not** used as the UI face). The UI face, Zen Kaku
  Gothic New, is loaded via Google Fonts CDN in `colors_and_type.css`; self-host
  its TTFs here to ship offline. *See caveat below.*
- **`preview/`** — the Design System cards (color, type, spacing, components) that
  populate the Design System tab.
- **`ui_kits/app/`** — the headache-diary iOS UI kit: interactive screen
  recreations + reusable JSX components. Start at `ui_kits/app/index.html`.

### Caveats
- **Fonts are CDN-loaded, not self-hosted.** The sandbox can't fetch Google's TTFs
  to copy into `/fonts`. To ship offline, download Zen Kaku Gothic New and drop the
  TTFs in `/fonts`, then swap the `@import` for `@font-face`. (The uploaded
  `Apple_Braille.ttf` is a braille font and is intentionally **not** the UI face —
  if a different brand font was intended, please re-upload it.)
- **The brand is invented.** Validate the teal, the pain ramp, and the typeface
  with stakeholders before treating this as canonical.
- **The check-sheet (`.xlsx`) is canonical** — confirm monthly summary layout,
  symbols, legends, and patient-facing fields against it before implementation.
- **Known UI-kit gap:** add a Home entry point for free-text app-improvement
  requests. Store locally, protect like symptom data, and never auto-send.