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.
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.
@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 AnimationSignature 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 (
Paletteon macOS) withNVColor.accent; keep amber only throughNVColor.warning. - AI output:
NVColor.ai/aiSoft+NVAIBadge— never unmarked. - Do not call
withAnimationdirectly for product motion: usewithNVAnimation/.nvAnimationso Reduce Motion is honoured.