SPB Git

Repository Public

DESIGN.md 8.1 KB

# SPNotesDesign — Note Visual System 2.0 « Graphite & Ultramarine · Lumen »

Library product SPNotesDesign of the SPNotesCore package (SwiftUI, iOS 18 / macOS 15, no dependency). It is the Swift side of SPEC §5; the web keeps the same tokens as CSS custom properties. It is not re-exported by the SPNotesCore umbrella: import SPNotesDesign explicitly. It contains tokens and reusable components only — no app code.

sh
SPN_ONLY=Design swift test --scratch-path .build-design      # 21 tests, 4 suites

# 1. Colour — NVColor

NVColor.<token> is a dynamic Color (light / dark follows the view's appearance: UIColor dynamic provider on iOS, NSColor(name:dynamicProvider:) on macOS). NVColor.Token.<token> gives the raw values (lightHex, darkHex, light / dark as NVRGB, color(for: ColorScheme) for a fixed colour); NVColor.Token.all lists the 18 tokens.

token light dark token light dark
bg #F9FBFD #0D1016 lineStrong #CCD0D5 #333640
bgElevated #FFFFFF #15181F accent #2F5DDB #7CA5FF
bgSunken #F0F3F6 #080A0F accentFg #FBFCFE #090F1C
bgSidebar #F3F6F9 #0A0C12 accentSoft #E5F0FF #1B2A4C
bgHover #EAEDF2 #1D2028 ai #7E41D2 #B999FB
fg #151922 #E8EBEF aiSoft #F3ECFF #302249
fgMuted #535862 #A0A5AE success #008B4E #5BC083
fgFaint #848992 #6A6F77 warning #D98B09 #F2AF48
line #E1E4E8 #22252D danger #CC272E #F26A64

Rules: ultramarine accent is the only interactive hue; violet ai marks anything produced by a model (always with NVAIBadge); amber survives only as warning. NVColor.lumen is the signature gradient accent → ai at 135° (hero surfaces, capture pulse, graph edges, AI shimmer). NVRGB offers init?(hexString:) (#rgb, #rrggbb, #rrggbbaa), relativeLuminance and NVRGB.contrast(_:_:) (WCAG 2).

# Measured contrast (WCAG 2 ratio, computed by ColorTokenTests from the tokens)

Text pairs, asserted ≥ 4.5 : 1 in both appearances:

pair light dark pair light dark
fg on bg 16.62 15.81 accent on bg 5.82 7.61
fg on bgElevated 17.36 14.47 accent on bgElevated 6.08 6.96
fg on bgSunken 15.62 16.48 accentFg on accent 5.93 7.60
fg on bgSidebar 16.03 16.22 accent on accentSoft 5.25 5.53
fg on bgHover 14.93 12.97 ai on bg 5.73 7.87
fgMuted on bg 6.51 8.26 ai on bgElevated 5.98 7.20
fgMuted on bgElevated 6.80 7.56 ai on aiSoft 5.12 5.96
fgMuted on bgSidebar 6.28 8.47 fgMuted on bgSunken 6.12 8.61

Below 4.5 — not for body text:

pair light dark rule
fgFaint on bg 3.02 4.15 placeholders, decorative metadata, disabled text only (asserted ≥ 3.0)
fgFaint on bgElevated 3.15 3.79 same
success on bg / bgElevated 4.06 / 4.25 9.28 / 8.49 light: icons, dots, large text; not small text
warning on bg / bgElevated 2.82 / 2.94 10.56 / 9.66 light: fills and icons with a text label in fg; never text
danger on bg / bgElevated 4.38 / 4.57 7.57 / 6.93 light: fine on bgElevated, marginal on bg

The status values are the specification's and were not altered. Consequence to know: NVChip with tone .success, .warning or .danger writes 11 pt text in the status hue, which is under AA in light mode — pair those chips with an icon, or use .neutral for information that must be read. (Reported to the lead; a darker light-mode status text token would fix it on both web and native.)

# 2. Typography — NVFont

style size (pt) weight design scales with
micro 11 medium sans caption2
ui / uiStrong 13 regular / semibold sans footnote
code 13 regular monospaced footnote
body 16 regular sans body
reading 16 (17 on iPhone) regular serif body
h3 / h2 20 / 24 semibold serif title3 / title2
h1 / display 30 / 40 bold serif title / largeTitle

Text("…").nvFont(.h1) follows Dynamic Type (@ScaledMetric relative to the text style); NVFont.fixed(.h1) is the exact base size. Serif = Font.Design.serif (New York). Reading column: NVSpace.readingMeasure (680 pt).

# 3. Spacing, radius, elevation

NVSpace: xxs 2, xs 4, sm 8, md 12, lg 16, xl 24, xxl 32, xxxl 48, huge 64. NVRadius: xs 4, sm 6, md 10, lg 14, xl 20, pill 999; NVRadius.shape(_:) = continuous rounded rectangle. NVElevation through .nvCard(), .nvPop(), .nvGlass() (or .nvElevation(_:radius:)): card = bgElevated + hairline + 1 px shadow; pop = shadow offset 16 / blur 40; glass = .ultraThinMaterial under a 66 % bgElevated surface + hairline, and an opaque surface under Reduce Transparency.

# 4. Motion — NVMotion

Tokens: instant 90 ms, fast 160 ms, base 240 ms, slow 420 ms, ambient 900 ms, exit (160 ms, exit easing), spring (response 0.38, damping 0.82). Easings NVMotion.Curve.standard = cubic-bezier(.2,.8,.2,1), .exit = cubic-bezier(.4,0,1,1).

Reduce Motion rule. Every helper takes it into account; under Reduce Motion an animation is a linear cross-fade of at most NVMotion.reducedMaxDuration (120 ms): no movement, no scale, no spring, no stagger.

swift
@Environment(\.accessibilityReduceMotion) private var reduceMotion
withNVAnimation(.base, reduceMotion: reduceMotion) { showPanel.toggle() }
view.nvAnimation(.fast, value: isSelected)                 // reads the environment itself
NVMotion.animation(.spring, reduceMotion: reduceMotion)    // an Animation

Signature motions:

# motion API under Reduce Motion
1 Living Pages .nvBlockReveal(index:) — rise 6 pt + fade, 18 ms stagger, first 24 blocks only (NVMotion.staggerDelay) fade ≤ 120 ms, no stagger
2 Morphing Editor NVMorphingToolbar(id:) { … } cross-fade
3 Knowledge Connections NVEdgeShape (animatable progress trim), NVEdgeLine(from:to:) draws itself, Lumen stroke appears complete, fades in
4 Fluid Navigation .nvSharedTitle(id:in:isSource:) (matched geometry) no geometry match, cross-fade
5 Intelligent Panels .nvPanelTransition(edge:) — slide + blur cross-fade
6 Quick Capture .nvCaptureScaleIn() (animate with .fast, 160 ms) and .nvCapturePulse(trigger:) (Lumen ring) fade; static ring that fades
7 Semantic Zoom NVSemanticZoom(level:) { level in … } cross-dissolve; the app owns the scroll anchor cross-fade ≤ 120 ms

NVTransition.blockReveal / morph / panel(edge:) / captureScaleIn / semanticZoom (reduceMotion:) give the raw AnyTransitions for custom containers.

# 5. Components

component use
NVCard { … } padded card surface
NVChip("tag", systemImage:, tone:, isSelected:, action:) tag, filter, status pill (NVTone: neutral, accent, ai, success, warning, danger)
NVSectionHeader("Titre", subtitle:) { accessory } section title, header trait
NVEmptyState(systemImage:title:message:actionTitle:action:) centred empty state
NVAIBadge(model:style:) the mandatory visible marker « Généré par IA » (.compact = « IA »; VoiceOver always reads the long form)
NVCitationChip(index:label:action:) numbered source of a grounded answer / research citation
NVToolbarGlass { … } translucent toolbar chrome
NVProgressDots(count:current:) / NVProgressDots() determinate steps / indeterminate activity (static under Reduce Motion)

Strings are French (source language). Debug builds include a gallery preview (NVGallery_Previews, light and dark).

# 6. Adoption notes for the apps

  • Replace the amber accent (Palette on macOS) with NVColor.accent; keep amber only through NVColor.warning.
  • AI output: NVColor.ai / aiSoft + NVAIBadge — never unmarked.
  • Do not call withAnimation directly for product motion: use withNVAnimation / .nvAnimation so Reduce Motion is honoured.
Files main
Menu

Theme